libasciidoc

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 14, 2020 License: Apache-2.0 Imports: 10 Imported by: 8

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:

    ConvertToHTML(r io.Reader, output io.Writer, config configuration.Configuration) (types.Metadata, error) 

2. Converting a file (given its name) into an HTML document:

   ConvertFileToHTML(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 `<body>` part, as well as the other attributes of the source 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 = `<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.WithMacroTemplate(tmpl.Name(), tmpl))
```

== 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(output io.Writer, config configuration.Configuration) (types.Metadata, 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(r io.Reader, output io.Writer, config configuration.Configuration) (types.Metadata, 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.

Directories

Path Synopsis
cmd
pkg
log

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL