bytesparadise/libasciidoc

= Libasciidoc

Libasciidoc is an open source Go library to convert from Asciidoc to HTML.

== Supported syntax

Although it does not support the full Asciidoc/Asciidoctor syntax, Libasciidoc already provides users with the following features:

Title and Sections level 1 to 6
Document authors and revision
Attribute declaration and substitution
Paragraphs and admonition paragraphs
Delimited Blocks (fenced blocks, listing blocks, example blocks, comment blocks, quoted blocks, sidebar blocks, verse blocks, open blocks)
Source code highlighting of delimited blocks (use either chroma or pygments as the source-highlighter)
Literal blocks (paragraph starting with a space, with the +++....+++ delimiter or with the [literal] attribute)
Quoted text (bold, italic, monospace, marked, superscript and subscript) and substitution prevention using the backslash (\) character
Single and double quoted typographic quotes (e.g. 'single' and "double")
Explicit and implicit curved apostrophe
Copyright (C), Registered (R), and Trademark (TM) symbols
Passthrough (wrapping with a single plus or a triple plus, or using the +++pass:[]+++ or +++pass:q[]+++ macros)
External links in paragraphs (https://, http://, ftp://, irc://, mailto:)
Inline images in paragraphs (image:)
Image blocks (image::)
Icons including font, graphic icons, both in admonition blocks and inline (icon:)
Element attributes (ID, link, title, role, etc.) including short-hand ([#id.role1.role2])
Ordered lists including custom numbering types (arabic, upperroman, lowergreek, and so forth)
Unordered lists including bullet styles
Labeled lists, including [horizontal] and [qanda] styles
Nesting of links of different types & attributes
Tables (basic support: header line and cells on multiple lines, top-level table styles)
Horizontal rules (thematic breaks) and page breaks
Table of contents
YAML front-matter

See also the link:LIMITATIONS.adoc[known limitations] page for differences between Asciidoc/Asciidoctor and Libasciidoc.

Further elements will be supported in the future. Feel free to open issues https://github.com/bytesparadise/libasciidoc/issues[here] to help prioritizing the upcoming work.

=== Syntax Highlighting

When enabled, syntax highlighting in [source] blocks is backed by the https://github.com/alecthomas/chroma[Chroma libray]. The defaut class prefix is tok-, and it can be overridden at the document level using the chroma-class-prefix attribute, or from the command line interface:

[source]

:chroma-class-prefix: myprefix- <1> :chroma-class-prefix: <2>

<1> classes with a custom prefix <2> classes without any prefix ``` $ libasciidoc -o - -a chroma-class-prefix=myprefix- mydoc.adoc ``` You can also use the `chroma` CLI (see https://github.com/alecthomas/chroma/releases[the release page to download the binary]) to generate your CSS with the default prefix or the one of your choice: ``` $ chroma -s lovelace --html --html-prefix=tok- --html-styles ``` == Output Formats (backend) Using `-b` (or `--backend`) the following formats are supported: * `html5` (also `html`), this is the default * `xhtml5` (also `xhtml`) == Installation To build libasciidoc and make it available on the command line, do this: $ git clone https://github.com/bytesparadise/libasciidoc.git $ cd libasciidoc $ make install If `$GOPATH/bin` is already in `$PATH`, then you should be good. Otherwise, for Linux and macOS users, you can run the following command: $ sudo ln -s "$PWD/bin/libasciidoc" /usr/local/bin/libasciidoc == Usage === Command Line The libasciidoc library includes a minimalist command line interface to generate the HTML content from a given file: ``` $ libasciidoc -s content.adoc ``` use `libasciidoc --help` to check all available options. === Code integration Libasciidoc provides 2 functions to convert an Asciidoc content into HTML: 1. Converting an `io.Reader` into an HTML document: Convert(r io.Reader, output io.Writer, config *configuration.Configuration) (types.Metadata, error) 2. Converting a file (given its name) into an HTML document: ConvertFile(output io.Writer, config *configuration.Configuration) (types.Metadata, error) where the returned `types.Metadata` object contains the document's title which is not part of the generated HTML `` part, as well as the table of contents (even if not rendered) and other attributes of the document. All options/settings are passed via the `config` parameter. === Macro definition The user can define a macro by calling `renderer.WithMacroTemplate()` and passing return value to conversion functions. `renderer.WithMacroTemplate()` defines a macro by the given name and associates the given template. The template is an implementation of `renderer.MacroTemplate` interface (ex. `text.Template`) Libasciidoc calls `Execute()` method and passes `types.UserMacro` object to template when rendering. An example the following: ``` var tmplStr = `Example: {{.Value}}{{.Attributes.GetAsString "suffix"}}` var t = template.New("example") var tmpl = template.Must(t.Parse(tmplStr)) output := &strings.Builder{} content := strings.NewReader(`example::hello world[suffix=!!!!!]`) libasciidoc.Convert(content, output, renderer.WithMacroTemplate(tmpl.Name(), tmpl)) ``` == How to contribute Please refer to the link:CONTRIBUTE.adoc[Contribute] page. == License Libasciidoc is available under the terms of the https://raw.githubusercontent.com/bytesparadise/libasciidoc/LICENSE[Apache License 2.0]. == Trademark AsciiDoc is a trademark of the Eclipse Foundation

bytesparadise / libasciidoc

readme

[source]

:chroma-class-prefix: myprefix- <1> :chroma-class-prefix: <2>