Skip to content
A Golang library for processing Asciidoc files.
Go Other
  1. Go 99.5%
  2. Other 0.5%
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/libasciidoc
pkg
test
testsupport
.codecov.yml
.gitignore
.golangci.yml
.goreleaser.yml
.travis.yml
CHANGELOG.md
CONTRIBUTE.adoc
LICENSE
LIMITATIONS.adoc
Makefile
README.adoc
appveyor.yml
go.mod
go.sum
libasciidoc.go
libasciidoc_suite_test.go
libasciidoc_test.go
tools.go

README.adoc

Libasciidoc

GoDoc Go Report Card Build Status Codecov License

Libasciidoc is an open source Go library to convert from Asciidoc to HTML. It is is available under the terms of the Apache License 2.0.

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)

  • Literal blocks (paragraph starting with a space, with the .... delimiter or with the [literal] attribute)

  • Quoted text (bold, italic, monospace, superscript and subscript) and substitution prevention using the backslash (\) character

  • Passtrough (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::)

  • Element attributes (ID, link, title, role, etc.)

  • Labeled, ordered and unordered lists (with nested lists and attributes on items)

  • Tables (basic support: header line and cells on multiple lines)

  • Table of contents

  • YAML front-matter

See also the known limitations page for differences between Asciidoc/Asciidoctor and Libasciidoc.

Further elements will be supported in the future. Feel free to open issues here to help prioritizing the upcoming work.

Installation

$ go get -u github.com/bytesparadise/libasciidoc
$ make install

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:

    func ConvertToHTML(ctx context.Context, source io.Reader, output io.Writer, options renderer.Option...) (map[string]interface{}, error)
  2. Converting a file (given its name) into an HTML document:

    func ConvertFileToHTML(ctx context.Context, filename string, output io.Writer, options renderer.Option...) (map[string]interface{}, error)

where the returned map[string]interface{} object contains the document’s title which is not part of the generated HTML <body> part, as well as the other attributes of the source document.

For now, the sole option to pass as a last argument is renderer.IncludeHeaderFooter to include the <header> and <footer> elements in the generated HTML document or not. Default is false, which means that only the <body> part of the HTML document is generated.

Macro definition

The user can define a macro by calling renderer.DefineMacro() and passing return value to conversion functions.

renderer.DefineMacro() 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 = `<span>Example: {{.Value}}{{.Attributes.GetAsString "suffix"}}</span>`
var t = template.New("example")
var tmpl = template.Must(t.Parse(tmplStr))

output := &strings.Builder{}
content := strings.NewReader(`example::hello world[suffix=!!!!!]`)
libasciidoc.ConvertToHTML(context.Background(), content, output, renderer.DefineMacro(tmpl.Name(), tmpl))

How to contribute

Please refer to the Contribute page.

You can’t perform that action at this time.