lein-asciidoctor

Introduction

AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions. AsciiDoc documents can be created using any text editor and read "as-is", or rendered to HTML or any other format.

Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook 5 (or 4.5) and other formats. Asciidoctor is written in Ruby, but it has a binding to work on JVM using JRuby - AsciidoctorJ.

lein-asciidoctor is a Leiningen plugin that allows to generate documentation from AsciiDoc files in different formats using AsciidoctorJ.

Setup

To enable lein-asciidoctor for your project, put the following line in the :plugins vector of your project.clj file:

project.clj

:plugins [[lein-asciidoctor "0.1.12"]]

Configuration

To configure lein-asciidoctor, put the :asciidoctor parameter in the file project.clj. It could be a single configuration (simple map) or a collection of configurations (for multiple configuration).

project.clj

; single configuration
:asciidoctor {:sources "doc/*.ascii"}

; multiple configurations
:asciidoctor [{:sources ["doc1/*.adoc" "doc2/*.adoc"]
               :format :html5}
              {:sources "doc/*.ascii"
               :format :html}]

Supported formats

The Asciidoctor processor parses an AsciiDoc document and converts it to a variety of formats:

html5, html - HTML 5 markup. Default backend.
xhtml5 - XHTML 5 markup.
dockbook5, docbook - DocBook XML 5.0 markup.
docbook45 - DocBook XML 4.5 markup.

If no backend is indicated, the processor uses the default backend (html5).

Configuration parameters

Each configuration parameter could be a keyword (ex: :sources) or a string (ex: "sources"). You can combine this approaches if you need.

:sources: List of input sources. It is possible to use a single source or a vector of sources. To configure this parameter, you could also use a Glob Patterns. Default value: "src/asciidoc/*.asciidoc"
:excludes: List of glob patterns to prevent processing of some AsciiDoc files. It is also possible to use both variants: single pattern and collection of patterns.
:to-dir: Target directory. All generated files will be placed in this directory. By default, all output will be placed in the same directory.
:compact: Compact the output by removing blank lines. Possible values: true or false (default).
:header-footer: Suppress or allow the document header and footer in the output. Possible values: true (default) or false. For example, it renders only <body> content in HTML mode.
:header: Suppresses the rendering of the header. Possible values: true (default) or false.
:footer: Suppress or allow the document footer in the output. Possible values: true or false (default). For example, it suppresses footer element in HTML mode.
:toc: Add table of contents. Possible values: :auto, :left, :right. By default, ToC is not enabled.
:toc-title: Allows you to change the title of the TOC. Default value: "Table of Contents".
:toc-levels: By default, the TOC will display level 1 and level 2 section titles. You can set a different level with the toclevels attribute. Possible values: 1, 2 (default), 3, 4, 5.
:title: Configure the title of document. For example, it defines <title> element in HTML mode.
:no-title: Toggles the display of a document’s title.
:format: Backend output file format: :html5, :docbook45 and :docbook5 supported out of the box. You can also use the backend alias names :html (aliased to :html5) or :docbook (aliased to :docbook5). Defaults to :html. It is also possible to use keywords or strings as values: :html and "html" is the same.
:doctype: Document type: :article, :book, :manpage or :inline. Sets the root element when using the docbook format and the style class on the HTML body element when using the html format. The :book document type allows multiple level-0 section titles in a single document. The :manpage document type enables parsing of metadata necessary to produce a manpage. The :inline document type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element. Defaults to :article.
:source-highlight: Enable syntax hightlighter for source codes. Possible values: true (default) or false.
:extract-css: Extract CSS resources in the output directory. Default asciidoctor.css will be extracted always. CSS file for syntax hightlighter (coderay-asciidoctor.css) will be extracted if :source-highlight parameter is turned on.

Usage

To run lein-asciidoctor plugin, you need to execute the following command in the command line:

lein asciidoc

To enable this plugin at the compile stage (for example, during lein compile or lein uberjar), use the following Leiningen hook:

:hooks [lein-asciidoctor.plugin]

To show help for CLI, use:

lein help asciidoc

Examples

Detailed example

project.clj

:asciidoctor [{:sources ["doc/*.ascii"]
              :to-dir "doc-generated"
              :compact true
              :format :html5
              :extract-css true
              :toc :left
              :title "Just an example"
              :source-highlight true}]

As result you will get the following:

Directory doc will be scanned for input sources using pattern *.ascii.
All found sources will be converted into HTML files (:html5) in the output directory doc-generated:
- All spaces in the output text files will be trimmed.
- Table of contents will be placed at the left part of each HTML document.
- Each generated HTML document will have the title Just an example.
- Syntax hightlighter will be applied on each code block.
CSS files asciidoctor.css and coderay-asciidoctor.css will be extracted in the same output directory.

GitHub Pages

GitHub Pages for this project were also generated using lein-asciidoctor.

Example project

Just clone current repository and try to play with example project for better understanding how to use lein-asciidoctor.

Unit testing

To run unit tests:

lein with-profile dev midje

Useful links

Copyright and Licensing

See the LICENSE file for details.