• Stars
    star
    9
  • Rank 1,939,536 (Top 39 %)
  • Language
    Go
  • License
    GNU General Publi...
  • Created about 4 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

[mirror] Native Go module for parsing and converting asciidoc markup language.

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
  • 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 metadata or attribute references,

  • author(_x)
  • authorinitials(_x)
  • doctitle
  • email(_x)
  • firstname(_x)
  • idprefix
  • idseparator
  • lastname(_x)
  • last-update-label
  • middlename(_x)
  • nofooter
  • noheader
  • revdate
  • revnumber
  • revremark
  • sectids
  • sectnumlevels
  • sectnums
  • showtitle
  • table-caption
  • title-separator
  • version-label

Additional metadata 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
    • Partitioning large documents and using leveloffset
    • 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:

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.

More Repositories

1

go-bindata

A small utility which generates Go code from any file. Useful for embedding binary data in a Go program.
Go
186
star
2

pakakeh.go

[mirror] A collection of libraries and tools written in Go.
Go
49
star
3

rescached-go

Resolver (DNS) cache daemon.
Go
32
star
4

hunspell-id

Indonesia hunspell dictionary. Kamus Bahasa Indonesia untuk program hunspell.
Makefile
32
star
5

dsv

The Go library for working with delimited separated value (DSV).
Go
28
star
6

haminer

[mirror] Library and program to parse and forward HAProxy HTTP logs
Go
22
star
7

j2p

A tool to help migrating from JIRA to Phabricator
Go
13
star
8

tabula

A Go library for working with rows, columns, or matrix (deprecated, see https://github.com/shuLhan/share/tree/master/lib/tabula).
Go
11
star
9

go-mining

Data mining with Go.
Go
10
star
10

ciigo

[mirror] Go static website generator with asciidoc markup language
Go
10
star
11

rescached

Resolver cache daemon (deprecated). See https://github.com/shuLhan/rescached-go for new implementation.
C++
8
star
12

beku

Go simple package manager with GOPATH or vendor
Go
8
star
13

mattermost-integration

Libraries and tools for integrating with Mattermost
Go
7
star
14

sima

Sistem Informasi Manajemen Aset
PHP
7
star
15

arch-docker

Script to create docker images based on Arch Linux on x86_64.
Shell
4
star
16

vos

Vos is a program to process formatted data, i.e. CSV data. Vos is designed to process a large input file, a file where their size is larger than the size of memory, and can be tuned to adapt with your machine environment.
C
4
star
17

wvcgen

Wikipedia vandalism dataset generator
Go
3
star
18

gorankusu

[mirror] The Go module for programmatically run and load testing HTTP services
Go
3
star
19

gotp

[mirror] Command line interface for Time-based One Time Password (TOTP)
Go
2
star
20

thesis

Master Thesis: Detecting Vandalism on English Wikipedia Using LNSMOTE Resampling and Cascaded Random Forest Classifier
TeX
1
star
21

awwan

[mirror] Configuration management software, infrastructure as file and directory layout
Go
1
star
22

mdgo

[mirror] Go static website generator with markdown markup language
Go
1
star
23

gonduit

The Go library for working with Phabricator Conduit API
Go
1
star
24

karajo

[mirror] HTTP workers and manager with web user interface
Go
1
star
25

kait

Go
1
star
26

librextjs

Open source javascript framework.
JavaScript
1
star
27

tekstus

A Go library for working with text (deprecated, see: github.com/shuLhan/lib/text).
Go
1
star
28

libvos

A C-with-class library primarily for manipulating DSV data (reading and writing DSV data in any format), turns out it had more capabilities: DNS protocol, FTP protocol, a simple FTP server, OCI protocol, and reading/writing INI configuration file
C++
1
star
29

share

[Deprecated] A collection of libraries and tools written in Go. This module has been moved to https://git.sr.ht/~shulhan/pakakeh.go
Go
1
star