Guard::AsciiDoc is a plugin for Guard that uses Asciidoctor to convert watched AsciiDoc files to the specified output format.

AsciiDoc

https://asciidoc.org

Guard

https://github.com/guard/guard

Asciidoctor

https://github.com/asciidoctor/asciidoctor

Prerequisites

Guard::AsciiDoc is a plugin for Guard, which is a Ruby application you install using Ruby packaging. To run Guard with this plugin, you need Ruby 3.0 or better.

Run the following command to check which version of Ruby you have installed, if any:

$ ruby -v

If Ruby is not installed, you can install it using RVM (or, if you prefer, the package manager for your system). We generally recommend using RVM as it allows you to install gems without requiring elevated privileges or messing with system libraries.

Installation

Set up your Gemfile:

Gemfile

source 'https://rubygems.org'

gem 'guard-asciidoc'

Install the dependencies:

$ bundle config set --local path .bundle/gems
  bundle

Create a Guardfile at the root of the project by running:

$ bundle exec guard init

Now you can run Guard so it starts watching your files:

$ bundle exec guard

In the console, you should see:

INFO - Guard::AsciiDoc is now watching for changes
INFO - Guard is now watching at '/path/to/current/directory'

By default, the plugin looks for all AsciiDoc files in the project.

Configuration

You can then configure the options of the plugins. For example, if your docs are located in the docs folder, you can tell the plugin watch this folder instead of the root folder:

Guardfile

guard :asciidoc, watch_dir: 'docs'

You can also set AsciiDoc attributes:

Guardfile

guard :asciidoc, attributes: { 'toc' => '' }

If you want to convert to PDF, you first need to declare a dependency on the asciidoctor-pdf gem:

$ bundle add asciidoctor-pdf

Now set the :backend option to :pdf in Guardfile.

Guardfile

guard :asciidoc, backend: :pdf

You can also require an extension, such as Asciidoctor Diagram. You first need to declare a dependency on the asciidoctor-diagram gem:

$ bundle add asciidoctor-diagram

Now add asciidoctor-diagram to the :requires option in Guardfile.

Guardfile

guard :asciidoc, requires: ['asciidoctor-diagram']

If you want to output files to a build directory, such as build, set the :to_dir option in Guardfile. When the :to_dir option is specified, the directory structure of the input file is preserved (relative to the :watch_dir value, if present, or the project root otherwise).

Guardfile

guard :asciidoc, to_dir: 'build'

You can combine any of the options mentioned previously.

By default, the plugin looks for files that have the .adoc file extension. If you want to watch for files with other file extensions, or in other folders, you can set up a custom watcher in Guardfile. Note that if you define a watcher, the default watcher will not be created (and hence the :watch_dir option is not relevant).

Guardfile

guard :asciidoc
  watch %r{^docs/.+\.adoc$}
  watch(%r{^docs/.+\.rb$}) { 'docs' }
end

Copyright and License

Copyright © 2013-present Paul Rayner and Dan Allen. Use of this software is granted under the terms of the MIT License.

See the LICENSE for the full license text.

Trademarks

AsciiDoc® and AsciiDoc Language™ are trademarks of the Eclipse Foundation, Inc.