Setting Up a Writing/Development Environment

A proper Jekyll/AsciiDocsy environment has a few prerequisites.

The entire toolchain is Ruby-based, so once you have the right version of Ruby, it is pretty easy to get up and running.

The rest of what you’ll need to have a great experience with AsciiDocsy is a terminal emulator and a code editor.

Ruby

Other than a Ruby runtime environment, this codebase installs all dependencies using Bundler.

Check for a current Ruby version using ruby -v.

If you do not have Ruby installed, use Jekyll’s installation instructions.

Windows 10 users are strongly encouraged to use this guide to running Jekyll on Linux via WSL.
MacOS and Linux users are encouraged to install and manage Ruby using rbenv.
All else being equal, we recommend you install the latest stable release, so Ruby 2.7.x or 3.0.x (where x is the latest patch version). Jekyll 4.0.0 and the jekyll-asciidoc plugin both require Ruby 2.4.0 or later.

Terminal & Shell

Windows users still need a terminal to pass commands to the WSL shell. Try Windows Terminal, as recommended in the WSL2 setup article.

For MacOS users who do not already have a preferred terminal, iTerm2 is a common favorite.

If you are using a Linux desktop, I will assume you have a preferred terminal, and that it is KDE’s Konsole.

Zsh

On all platforms, I strongly recommend anyone new to the commandline/shell operations immediately install Zsh as default shell. Apple made Zsh the default shell for MacOS back in 2019 due to ease of use.

Zsh is basically a superset of Bash, so you can still use Bash scripting and all Bash commands, but Zsh makes it so much more intuitive and assisted.

There are lots of resources to enhance the experience, including the awesome addons package OhMyZsh! Use their Zsh install guide to make sure you’ve got the best setup.

Code Editor

Users perform most editing of AsciiDoc and YAML source files using software called a plaintext editor, a code editor, or an integrated development environment (IDE). The distinctions are not very important, as long as they integrate with AsciiDoc and YAML.

If you already have a preference, that’s the editor for you. If you are unsure, here is a brief guide to the top contenders.

VS Code

By far the most popular code editor today, VSC's renowned AsciiDoc support is maintained by the Asciidoctor community. Extend native YAML support with RedHat’s extension.

Atom

Maintained by GitHub, Atom was for years the main choice for AsciiDoc writers. You will want to add at least the asciidoc-language and asciidoc-preview packages.

InelliJ IDEA

More and more people swear by this freemium application and its AsciiDoc plugin as the ultimate writing combo. Extend YAML support.

AsciiDocFX

This AsciiDoc-focused editor gets better all the time, and its YAML handling is on par with the others. Installers work great for every platform, even if I find Java a little clunky (same would go for IntelliJ). Give AsciIDocFX a try.

The Asciidoctor project maintains a decent list of “text editors” with AsciIDoc support of some kind.

Feedback, please.