GitPlanet

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

Created with love in Canada, visit hostnodejs.com today

Feel like to post an Ad? Learn Details
All Projects → asciidoctor → asciidoctor-lein-plugin

asciidoctor / asciidoctor-lein-plugin

Licence: other
A Leiningen plugin for generating documentation using Asciidoctor

Programming Languages

clojure
4091 projects

Labels

documentationdocbookdocumentation-toolleiningenasciidocasciidoctorleindocumentation-generatorlein-plugin

Projects that are alternatives of or similar to asciidoctor-lein-plugin

Asciidoctor
💎 A fast, open source text processor and publishing toolchain, written in Ruby, for converting AsciiDoc content to HTML 5, DocBook 5, and other formats.
Stars: ✭ 3,905 (+14919.23%)
Mutual labels:  docbook, asciidoc, asciidoctor
lein-nrepl
A simple Leininingen plugin to start nREPL 0.4+
Stars: ✭ 19 (-26.92%)
Mutual labels:  leiningen, lein, lein-plugin
Asciidocfx
Asciidoc Editor and Toolchain written with JavaFX 16 (Build PDF, Epub, Mobi and HTML books, documents and slides)
Stars: ✭ 1,533 (+5796.15%)
Mutual labels:  docbook, asciidoc, asciidoctor
docscii
DocBook to AsciiDoc converter
Stars: ✭ 14 (-46.15%)
Mutual labels:  docbook, documentation-tool, asciidoc
cutedoc
Generate stunning documentation for any project using simple markdown files.
Stars: ✭ 16 (-38.46%)
Mutual labels:  documentation-tool, documentation-generator
eclipse-asciidoctor-editor
An eclipse editor for asciidoctor files
Stars: ✭ 45 (+73.08%)
Mutual labels:  asciidoc, asciidoctor
bitbucket-asciidoc-plugin
An add-on for Atlassian Bitbucket Server to render AsciiDoc files.
Stars: ✭ 20 (-23.08%)
Mutual labels:  asciidoc, asciidoctor
presidium
Presidium user documentation
Stars: ✭ 25 (-3.85%)
Mutual labels:  documentation-tool, documentation-generator
ocular
A documentation generator for our OSS frameworks
Stars: ✭ 42 (+61.54%)
Mutual labels:  documentation-tool, documentation-generator
live-documenter
.NET documentation generator and live reader. Generate documentation from .NET code and xml comments, fast, quick and easy.
Stars: ✭ 64 (+146.15%)
Mutual labels:  documentation-tool, documentation-generator
badge-generator
Magically generate Markdown badges for your docs 🛡️ 🦡 🧙
Stars: ✭ 104 (+300%)
Mutual labels:  documentation-tool, documentation-generator
b2
B2 makes it easy to build C++ projects, everywhere.
Stars: ✭ 38 (+46.15%)
Mutual labels:  docbook, asciidoctor
asciidoctor-htmlbook
Asciidoctor HTMLBook is an Asciidoctor backend for converting AsciiDoc documents to HTMLBook documents.
Stars: ✭ 31 (+19.23%)
Mutual labels:  asciidoc, asciidoctor
asciidoctor-rfc
AsciiRFC: an AsciiDoc/asciidoctor backend to produce RFC XML v3 (RFC 7991) and v2 (RFC 7749)
Stars: ✭ 14 (-46.15%)
Mutual labels:  asciidoc, asciidoctor
asciidoctor-katex
Asciidoctor extension for converting latexmath using KaTeX at build time
Stars: ✭ 16 (-38.46%)
Mutual labels:  asciidoc, asciidoctor
ank
ΛNK: Compile time docs verification and evaluation for Kotlin and Java (Temporarily moved to Arrow-kt)
Stars: ✭ 52 (+100%)
Mutual labels:  documentation-tool, documentation-generator
newdoc
The newdoc tool generates files formatted with AsciiDoc, which are used in Red Hat documentation.
Stars: ✭ 14 (-46.15%)
Mutual labels:  documentation-tool, documentation-generator
tygen
Modern documentation generator for TypeScript built with ReactJS
Stars: ✭ 23 (-11.54%)
Mutual labels:  documentation-tool, documentation-generator
numpydoc.el
Insert NumPy style docstrings in Python functions.
Stars: ✭ 33 (+26.92%)
Mutual labels:  documentation-tool, documentation-generator
NextBook
NextBook is quick and easy way to build technical books or documentation with markdown that run blazingly fast.
Stars: ✭ 153 (+488.46%)
Mutual labels:  documentation-tool, documentation-generator
View All Similar Projects ➔

lein-asciidoctor

Build Status Clojars Project

Introduction

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.

example

Setup

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

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).

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

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

Examples

Detailed example

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

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 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 LICENSE file for details.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].