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:
: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).
; 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
:asciidoctor [{:sources ["doc/*.ascii"]
:to-dir "doc-generated"
:compact true
:format :html5
:extract-css true
:toc :left
:title "Just an example"
:source-highlight true}]
-
Directory
doc
will be scanned for input sources using pattern*.ascii
. -
All found sources will be converted into HTML files (
:html5
) in the output directorydoc-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
andcoderay-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
Copyright © 2014 Vladislav Bauer and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.
See the LICENSE file for details.