Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asciidoctor/asciidoctor-lein-plugin

A Leiningen plugin for generating documentation using Asciidoctor
https://github.com/asciidoctor/asciidoctor-lein-plugin

asciidoc asciidoctor clj clojure docbook documentation documentation-generator documentation-tool lein lein-plugin leiningen

Last synced: 4 months ago
JSON representation

A Leiningen plugin for generating documentation using Asciidoctor

Awesome Lists containing this project

README 

        
: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 `` 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 `` 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 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 ===



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.