asciidoctor

README

asciidoctor-go

Author: Shulhan

The asciidoctor-go is the Go module to parse the AsciiDoc markup and convert it into HTML5.

Documentation

Go documentation.

Specifications

During reverse engineering the AsciiDoc markup, we write the syntax, rules, and format in SPECS.

Features

List of available formatting that are supported on current implementation. Each supported feature is linked to official AsciiDoc Language Documentation The numbered one is based on the old documentation.

• Document header
  • Document title. This including meta doctitle, showtitle! and subtitle.
  • Author information
  • Revision information
  • Metadata
• Preamble
• Sections
  • Titles as HTML headings
  • Auto-generated IDs
  • Custom IDs
  • Multiple Anchors
  • Links
  • Anchors
  • Numbering
  • Discrete headings
• Blocks
  • Title
  • Metadata
  • Delimited blocks
• Paragraph
  • Alignment
  • Line breaks (" +\n")
  • Lead style
• Text formatting
  • Bold and italic
  • Quotation Marks and Apostrophes
  • Subscript and Superscript
  • Monospace
• List
  • Unordered Lists (See Notes below)
    • Nested
    • Complex List Content
    • Custom Markers
  • Ordered Lists
    • Nested
    • Numbering Styles
  • Checklist
• Description List
  • Question and Answer Style List
• Tables
  • Columns
  • Column formatting
  • Cell formatting
  • Header row
  • Footer row
  • Table width
  • Table borders
  • Striping
  • Orientation
  • Nested tables
  • Table caption
  • Escaping the Cell Separator
• Horizontal Rules
  • Markdown-style horizontal rules
• Page Break
• URLs
  • Link to Relative Files
• Cross References
  • Automatic Anchors
  • Defining an Anchor
  • Internal Cross References
  • Customizing the Cross Reference Text
• Footnotes
• Include Directive
  • Anatomy
  • Processing
  • File resolution
• Images
• Video
  • YouTube and Vimeo videos
  • Supported Attributes
• Audio
• Admonition
• Sidebar
• Example
• Prose Excerpts, Quotes and Verses
  • Quote
  • Verse
• Comments
• Text Substitutions
  • Special Characters
  • Quotes
  • Attributes (reference)
  • Replacements
  • Preventing Substitutions
• Listing Blocks
• Passthroughs
  • Passthrough Blocks
• Open Blocks
• Predefined Attributes for Character Replacements

Supported document attribute references,

• author(_x)
• authorinitials(_x)
• doctitle
• email(_x)
• firstname(_x)
• idprefix
• idseparator
• lastname(_x)
• last-update-label
• leveloffset. Only on document attributes, not on include directive.
• middlename(_x)
• nofooter
• noheader
• revdate
• revnumber
• revremark
• sectids
• sectnumlevels
• sectnums
• showtitle
• table-caption
• title-separator
• version-label

Additional document attribute provides by this library,

• author_names - list of author full names separated by comma.

Notes

Unsupported markup

The following markup will not supported because its functionality is duplicate or inconsistent with others markup, or not secure,

• Header

  • Subtitle partitioning. Rationale: duplicate with 14.1.2 the "Main: sub" format

• Tables

  • Nested tables. Rationale: nested table is not a good way to present information. Never should it be.
  • Using different cell separator

• Include Directive

  • Select Portions of a Document to Include. Rationale: the parser would need to know the language to be included and parse the whole source code to check for comments and tags.
  • Include Content from a URI. Rationale: security and unreliable network connections.
  • Caching URI Content

Unordered list item with hyphen

The unordered list item with hyphen ('-') cause too much confusion and inconsistency.

Case one, given the following markup,

- Item 1
+
"A line
of quote"
-- Author

Is the "Author" the sub item in list or we are parsing author of quote paragraph?

Case two, the writer want to write em dash (— in HTML Unicode) but somehow the editor wrap it and start in new line.

As a reminder, the official documentation only recommend using hyphen for simple list item

You should reserve the hyphen for lists that only have a single level because the hyphen marker (-) doesn’t work for nested lists. -- https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/#basic-unordered-list

TODO

List of features which may be implemented,

• Sections
  • Section styles
• Paragraph
  • Line breaks
    • Per block "[%hardbreaks]"
    • All document ":hardbreaks:"
• Text formatting
  • Custom Styling With Attributes
• Tables
  • Delimiter-Separated Values
• Cross References
  • Inter-document Cross References
• Include Directive
  • AsciiDoc vs non-AsciiDoc files
  • Normalize Block Indentation
  • Include a File Multiple Times in the Same Document
  • Using an Include in a List Item
• Text Substitutions
  • Macros
  • Incremental Substitutions
• Passthroughs
  • Passthrough Macros

Bugs

Unknown. If you found one, please report it here.

Enhancements

Create tree that link Include directive. Once the included files changes, the parent should be re-converted too.

Include Node
parent -> Parent Node.

Miscellaneous

Changelog.

The following files compare the HTML generated by asciidoctor and this library:

• HTML file generated using asciidoctor
• HTML file using this library

Development

Repository:: Link to the source code.

Mailing list:: Link to discussion or where to send the patches.

Issues:: Link to open an issue or request for new feature.

Documentation

Overview

Package asciidoctor is the Go module to parse the AsciiDoc markup. Its currently support converting the asciidoc to HTML5.

Index

• Constants
• type Author
  • func (author *Author) FullName() string
• type Document
  • func Open(file string) (doc *Document, err error)
  • func Parse(content []byte) (doc *Document)
  • func (doc *Document) ToHTML(out io.Writer) (err error)
  • func (doc *Document) ToHTMLBody(out io.Writer) (err error)
  • func (doc *Document) ToHTMLEmbedded(out io.Writer) (err error)
• type DocumentAttribute
• type DocumentTitle
  • func (docTitle *DocumentTitle) String() string
• type Revision

Constants

const (
	DocAttrAuthor      = `author`       // May contain the first author full name only.
	DocAttrAuthorNames = `author_names` // List of author full names, separated by comma.
	DocAttrDescription = `description`
	DocAttrGenerator   = `generator`
	DocAttrKeywords    = `keywords`
)

List of document attribute.

const (
	// Version of this module.
	Version = `0.6.0`
)

Types

type Author

type Author struct {
	FirstName  string
	MiddleName string
	LastName   string
	Initials   string
	Email      string
}

Author of document.

func (*Author) FullName

func (author *Author) FullName() string

FullName return the concatenation of author first, middle, and last name.

type Document

type Document struct {
	Attributes DocumentAttribute

	Revision Revision

	Title DocumentTitle

	Authors []*Author

	TOCLevel int
	// contains filtered or unexported fields
}

Document represent content of asciidoc that has been parsed.

func Open

func Open(file string) (doc *Document, err error)

Open the ascidoc file and parse it.

func Parse

func Parse(content []byte) (doc *Document)

Parse the content into a Document.

func (*Document) ToHTML

func (doc *Document) ToHTML(out io.Writer) (err error)

ToHTML convert the Document object into full HTML document.

func (*Document) ToHTMLBody

func (doc *Document) ToHTMLBody(out io.Writer) (err error)

ToHTMLBody convert the Document object into HTML with body only, this is including header, content, and footer.

func (*Document) ToHTMLEmbedded

func (doc *Document) ToHTMLEmbedded(out io.Writer) (err error)

ToHTMLEmbedded convert the Document object into HTML with content only, without header and footer.

type DocumentAttribute

type DocumentAttribute struct {
	Entry       map[string]string
	LevelOffset int
}

DocumentAttribute contains the mapping of global attribute keys in the headers with its value.

type DocumentTitle

type DocumentTitle struct {
	Main string
	Sub  string
	// contains filtered or unexported fields
}

DocumentTitle contains the main and optional sub title.

func (*DocumentTitle) String

func (docTitle *DocumentTitle) String() string

String return the combination of main and subtitle separated by colon or meta `title-separator` value.

type Revision

type Revision struct {
	Number string
	Date   string
	Remark string
}

Revision contains the document version, date, and remark.