README
¶
= Libasciidoc
image:https://godoc.org/github.com/bytesparadise/libasciidoc?status.svg["GoDoc", link="https://godoc.org/github.com/bytesparadise/libasciidoc"]
image:https://goreportcard.com/badge/github.com/bytesparadise/libasciidoc["Go Report Card", link="https://goreportcard.com/report/github.com/bytesparadise/libasciidoc"]
image:https://travis-ci.org/bytesparadise/libasciidoc.svg?branch=master["Build Status", link="https://travis-ci.org/bytesparadise/libasciidoc"]
image:https://codecov.io/gh/bytesparadise/libasciidoc/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/bytesparadise/libasciidoc"]
image:https://img.shields.io/badge/License-Apache%202.0-blue.svg["License", link="https://opensource.org/licenses/Apache-2.0"]
Libasciidoc is an open source Go library to convert from Asciidoc to HTML.
It is is available under the terms of the https://raw.githubusercontent.com/bytesparadise/libasciidoc/LICENSE[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 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.
== 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.
== How to contribute
Please refer to the link:CONTRIBUTE.adoc[Contribute] page.
Documentation
¶
Overview ¶
Package libasciidoc is an open source Go library that converts Asciidoc content into HTML.
Index ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // BuildCommit lastest build commit (set by Makefile) BuildCommit = "" // BuildTag if the `BuildCommit` matches a tag BuildTag = "" // BuildTime set by build script (set by Makefile) BuildTime = "" )
Functions ¶
func ConvertFileToHTML ¶
func ConvertFileToHTML(ctx context.Context, filename string, output io.Writer, options ...renderer.Option) (map[string]interface{}, error)
ConvertFileToHTML converts the content of the given filename into an HTML document. The conversion result is written in the given writer `output`, whereas the document metadata (title, etc.) (or an error if a problem occurred) is returned as the result of the function call.
func ConvertToHTML ¶
func ConvertToHTML(ctx context.Context, r io.Reader, output io.Writer, options ...renderer.Option) (map[string]interface{}, error)
ConvertToHTML converts the content of the given reader `r` into a full HTML document, written in the given writer `output`. Returns an error if a problem occurred
Types ¶
This section is empty.
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.