Using the Library

Overview

libasciidoc can be used as a Go library to parse and render AsciiDoc documents programmatically. This is useful if you are building a documentation tool, a CMS, a static site generator, or any application that needs to process AsciiDoc content.

Installation

go get github.com/lukewilliamboswell/libasciidoc

Core API

The public API lives in the asciidoc package. There are two main functions:

Convert

Reads AsciiDoc from an io.Reader and writes the rendered output to an io.Writer:

import "github.com/lukewilliamboswell/libasciidoc/asciidoc"

metadata, err := asciidoc.Convert(reader, writer, config)

ConvertFile

Reads AsciiDoc from a file path and writes the rendered output to an io.Writer. The input filename is set via the configuration:

config := configuration.NewConfiguration(
    configuration.WithFilename("document.adoc"),
)
metadata, err := asciidoc.ConvertFile(writer, config)

Configuration

Configuration is built using functional options from the configuration package. Common options include:

configuration.WithBackEnd(backend) — set output format
configuration.WithAttribute(key, value) — set document attributes
configuration.WithCSS(path) — add CSS stylesheets
configuration.WithHeaderFooter(bool) — include or omit HTML wrapper
configuration.WithFilename(path) — set the input filename

Metadata

Both Convert and ConvertFile return a types.Metadata struct containing:

Title — the document title
TableOfContents — the generated table of contents structure
Authors — document authors
Attributes — resolved document attributes

Custom Macros

libasciidoc supports registering custom macro templates that extend the AsciiDoc syntax with your own rendering logic.