Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Build Status Clojars Project


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.



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

; Use latest version instead of "X.X.X"
:plugins [[lein-asciidoctor "X.X.X"]]


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.

  • manpage - Manual page for Unix-like operating systems.

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.


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"


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.


Target directory. All generated files will be placed in this directory. By default, all output will be placed in the same directory.


Compact the output by removing blank lines. Possible values: true or false (default).


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.


Suppresses the rendering of the header. Possible values: true (default) or false.


Suppress or allow the document footer in the output. Possible values: true or false (default). For example, it suppresses footer element in HTML mode.


Add table of contents. Possible values: :auto, :left, :right. By default, ToC is not enabled.


Allows you to change the title of the TOC. Default value: "Table of Contents".


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.


Configure the title of document. For example, it defines <title> element in HTML mode.


Toggles the display of a document’s title.


Backend output file format: :html5, :docbook45, :docbook5 and :manpage 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.


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.


Enable syntax hightlighter for source codes. Possible values: true or false (default).


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.


Set safe mode level: unsafe(0), safe(1), server(10) or secure(20). Disables potentially dangerous macros in source files, such as include::[]. If not set, the safe mode level defaults to unsafe when Asciidoctor is invoked. It is possible to use text values in different casses (like safe, unsafe, SAFE, etc), keywords (:safe, :unsafe, etc.) or numbers (0, 1, etc.). Default value: UNSAFE.


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


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}]
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 test

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.