:author: Vladislav Bauer :email: bauer.vlad@gmail.com = lein-asciidoctor =
image:https://travis-ci.org/asciidoctor/asciidoctor-lein-plugin.svg?branch=master["Build Status", link="https://travis-ci.org/asciidoctor/asciidoctor-lein-plugin"] image:https://img.shields.io/clojars/v/lein-asciidoctor.svg["Clojars Project" link="https://clojars.org/lein-asciidoctor"]
== Introduction ==
link:http://www.methods.co.nz/asciidoc/[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.
link:http://asciidoctor.org[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 link:http://jruby.org[JRuby] - link:https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ].
link:https://github.com/asciidoctor/asciidoctor-lein-plugin[lein-asciidoctor] is a link:http://leiningen.org[Leiningen] plugin that allows to generate documentation from AsciiDoc files in different formats using AsciidoctorJ.
image::https://raw.githubusercontent.com/asciidoctor/asciidoctor-lein-plugin/master/misc/example.png[]
== Setup ==
To enable lein-asciidoctor for your project, put the following line in the :plugins vector of your project.clj file:
== 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"}
=== Supported formats ===
The Asciidoctor processor parses an AsciiDoc document and converts it to a variety of formats:
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 link:http://en.wikipedia.org/wiki/Glob_(programming)[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, :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.
: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 or false (default).
: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.
:safe:: 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.
== Usage ==
lein compile or lein uberjar), use the following Leiningen hook:
[source,clojure]== Examples ==
=== Detailed example ===
.As result you will get the following:
doc will be scanned for input sources using pattern *.ascii.: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.asciidoctor.css and coderay-asciidoctor.css will be extracted in the same output directory.=== GitHub Pages ===
link:http://asciidoctor.github.io/asciidoctor-lein-plugin[GitHub Pages] for this project were also generated using lein-asciidoctor.
=== Example project ===
Just clone current repository and try to play with link:https://github.com/asciidoctor/asciidoctor-lein-plugin/tree/master/example[`example`] project for better understanding how to use lein-asciidoctor.
== 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 link:https://github.com/asciidoctor/asciidoctor-lein-plugin/blob/master/LICENSE.adoc[LICENSE] file for details.