Guard::AsciiDoc
Guard::AsciiDoc is a plugin for Guard that uses Asciidoctor to convert watched AsciiDoc files to the specified output format.
- AsciiDoc
- Guard
- 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:
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:
guard :asciidoc, watch_dir: 'docs'You can also set AsciiDoc attributes:
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.
guard :asciidoc, backend: :pdfYou 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.
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).
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).
guard :asciidoc
watch %r{^docs/.+\.adoc$}
watch(%r{^docs/.+\.rb$}) { 'docs' }
endCopyright 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.