asciidoctor-lein-plugin
asciidoctor-lein-plugin copied to clipboard
A Leiningen plugin for generating documentation using Asciidoctor
:author: Vladislav Bauer :email: [email protected] = 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:
[source,clojure] .project.clj
; Use latest version instead of "X.X.X" :plugins [[lein-asciidoctor "X.X.X"]]
== 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).
[source,clojure] .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.
- 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.
: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 ==
To run lein-asciidoctor plugin, you need to execute the following command in the command line: [source,bash]
lein asciidoc
To enable this plugin at the compile stage (for example, during lein compile
or lein uberjar
), use the following Leiningen hook:
[source,clojure]
:hooks [lein-asciidoctor.plugin]
To show help for CLI, use: [source,bash]
lein help asciidoc
== Examples ==
=== Detailed example ===
[source,clojure] .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 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 titleJust 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 ===
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.
== Unit testing == To run unit tests: [source,bash]
lein test
== Useful links ==
- link:http://www.methods.co.nz/asciidoc/[Full AsciiDoc documentation]
- link:http://powerman.name/doc/asciidoc[AsciiDoc cheatsheet]
- link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference]
- link:http://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer’s Guide]
- link:http://www.compileonline.com/try_asciidoc_online.php[Try AsciiDoc Online]
== 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.