{"id":15010631,"url":"https://github.com/asciidoctor/asciidoctor-lein-plugin","last_synced_at":"2025-10-24T00:42:18.158Z","repository":{"id":19739023,"uuid":"22995561","full_name":"asciidoctor/asciidoctor-lein-plugin","owner":"asciidoctor","description":"A Leiningen plugin for generating documentation using Asciidoctor","archived":false,"fork":false,"pushed_at":"2018-11-13T10:34:26.000Z","size":214,"stargazers_count":25,"open_issues_count":3,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-30T00:00:38.919Z","etag":null,"topics":["asciidoc","asciidoctor","clj","clojure","docbook","documentation","documentation-generator","documentation-tool","lein","lein-plugin","leiningen"],"latest_commit_sha":null,"homepage":"http://asciidoctor.github.io/asciidoctor-lein-plugin","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asciidoctor.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.adoc","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-08-15T16:24:57.000Z","updated_at":"2024-09-27T01:29:39.000Z","dependencies_parsed_at":"2022-08-21T15:00:55.514Z","dependency_job_id":null,"html_url":"https://github.com/asciidoctor/asciidoctor-lein-plugin","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-lein-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-lein-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-lein-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asciidoctor%2Fasciidoctor-lein-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asciidoctor","download_url":"https://codeload.github.com/asciidoctor/asciidoctor-lein-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247493135,"owners_count":20947662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asciidoc","asciidoctor","clj","clojure","docbook","documentation","documentation-generator","documentation-tool","lein","lein-plugin","leiningen"],"created_at":"2024-09-24T19:35:09.052Z","updated_at":"2025-10-24T00:42:13.121Z","avatar_url":"https://github.com/asciidoctor.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":":author: Vladislav Bauer\n:email: bauer.vlad@gmail.com\n= lein-asciidoctor =\n\nimage:https://travis-ci.org/asciidoctor/asciidoctor-lein-plugin.svg?branch=master[\"Build Status\", link=\"https://travis-ci.org/asciidoctor/asciidoctor-lein-plugin\"]\nimage:https://img.shields.io/clojars/v/lein-asciidoctor.svg[\"Clojars Project\" link=\"https://clojars.org/lein-asciidoctor\"]\n\n== Introduction ==\n\nlink: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.\n\nlink: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].\n\nlink: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.\n\nimage::https://raw.githubusercontent.com/asciidoctor/asciidoctor-lein-plugin/master/misc/example.png[]\n\n\n== Setup ==\n\nTo enable lein-asciidoctor for your project, put the following line in the :plugins vector of your project.clj file:\n\n[source,clojure]\n.project.clj\n----\n; Use latest version instead of \"X.X.X\"\n:plugins [[lein-asciidoctor \"X.X.X\"]]\n----\n\n\n== Configuration ==\n\nTo 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).\n\n[source,clojure]\n.project.clj\n----\n; single configuration\n:asciidoctor {:sources \"doc/*.ascii\"}\n\n; multiple configurations\n:asciidoctor [{:sources [\"doc1/*.adoc\" \"doc2/*.adoc\"]\n               :format :html5}\n              {:sources \"doc/*.ascii\"\n               :format :html}]\n----\n\n\n=== Supported formats ===\n\nThe Asciidoctor processor parses an AsciiDoc document and converts it to a variety of formats:\n\n* *html5*, *html* - HTML 5 markup. Default backend.\n* *xhtml5* - XHTML 5 markup.\n* *dockbook5*, *docbook* - DocBook XML 5.0 markup.\n* *docbook45* - DocBook XML 4.5 markup.\n* *manpage* - Manual page for Unix-like operating systems.\n\nIf no backend is indicated, the processor uses the default backend (html5).\n\n\n=== Configuration parameters ===\n\nEach configuration parameter could be a keyword (ex: `:sources`) or a string (ex: `\"sources\"`). You can combine this approaches if you need.\n\n*: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\"`\n\n*: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.\n\n*:to-dir*:: Target directory. All generated files will be placed in this directory. By default, all output will be placed in the same directory.\n\n*:compact*:: Compact the output by removing blank lines. Possible values: true or false (default).\n\n*:header-footer*:: Suppress or allow the document header and footer in the output. Possible values: true (default) or false. For example, it renders only `\u003cbody\u003e` content in HTML mode.\n\n*:header*:: Suppresses the rendering of the header. Possible values: true (default) or false.\n\n*: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.\n\n*:toc*:: Add table of contents. Possible values: :auto, :left, :right. By default, ToC is not enabled.\n\n*:toc-title*:: Allows you to change the title of the TOC. Default value: \"Table of Contents\".\n\n*: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.\n\n*:title*:: Configure the title of document. For example, it defines `\u003ctitle\u003e` element in HTML mode.\n\n*:no-title*:: Toggles the display of a document’s title.\n\n*: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.\n\n*: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`.\n\n*:source-highlight*:: Enable syntax hightlighter for source codes. Possible values: true or false (default).\n\n*: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.\n\n*: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.\n\n\n== Usage ==\n\nTo run lein-asciidoctor plugin, you need to execute the following command in the command line:\n[source,bash]\n----\nlein asciidoc\n----\n\nTo enable this plugin at the compile stage (for example, during `lein compile` or `lein uberjar`), use the following Leiningen hook:\n[source,clojure]\n----\n:hooks [lein-asciidoctor.plugin]\n----\n\nTo show help for CLI, use:\n[source,bash]\n----\nlein help asciidoc\n----\n\n\n== Examples ==\n\n=== Detailed example ===\n\n[source,clojure]\n.project.clj\n----\n:asciidoctor [{:sources [\"doc/*.ascii\"]\n              :to-dir \"doc-generated\"\n              :compact true\n              :format :html5\n              :extract-css true\n              :toc :left\n              :title \"Just an example\"\n              :source-highlight true}]\n----\n\n.As result you will get the following:\n* Directory `doc` will be scanned for input sources using pattern `*.ascii`.\n* All found sources will be converted into HTML files (`:html5`) in the output directory `doc-generated`:\n** All spaces in the output text files will be trimmed.\n** Table of contents will be placed at the left part of each HTML document.\n** Each generated HTML document will have the title `Just an example`.\n** Syntax hightlighter will be applied on each code block.\n* CSS files `asciidoctor.css` and `coderay-asciidoctor.css` will be extracted in the same output directory.\n\n=== GitHub Pages ===\n\nlink:http://asciidoctor.github.io/asciidoctor-lein-plugin[GitHub Pages] for this project were also generated using lein-asciidoctor.\n\n=== Example project ===\n\nJust 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.\n\n\n== Unit testing ==\nTo run unit tests:\n[source,bash]\n----\nlein test\n----\n\n\n==  Useful links ==\n\n* link:http://www.methods.co.nz/asciidoc/[Full AsciiDoc documentation]\n* link:http://powerman.name/doc/asciidoc[AsciiDoc cheatsheet]\n* link:http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference]\n* link:http://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer’s Guide]\n* link:http://www.compileonline.com/try_asciidoc_online.php[Try AsciiDoc Online]\n\n\n== Copyright and Licensing ==\n\nCopyright © 2014 Vladislav Bauer and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.\n\nSee the link:https://github.com/asciidoctor/asciidoctor-lein-plugin/blob/master/LICENSE.adoc[LICENSE] file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasciidoctor%2Fasciidoctor-lein-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasciidoctor%2Fasciidoctor-lein-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasciidoctor%2Fasciidoctor-lein-plugin/lists"}