Changelog for asciidoctor-go

The ":leveloffset:" on document attribute allow increment or decrement the heading level on included files.

Reference: https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/

Previously, an empty line before Document Title cause the parser stop parsing the document header, now an empty lines are skipped. Also document attribute can be place anywhere, either before or after title, and in between attributes; now it can be only placed after revision or author or title.

Any custom ID on the first section always replaced with the subsection because, first, when detecting preamble we did not check for line with kind ID "[[…​]]" an short ID "[#…​]". Second, when parsing preamble we did not stop when we found line kind ID and short ID.

This preamble thing is kind of annoying. We need to revisit again how to detect preamble, maybe not calling separate block parser, but making it linear as the default first child of parent element.

The golangci-lint does not output any results anymore Either we are getting good at writing Go or the linter itself is become less good. We also have seen that the latest golangci-lint is failed to build with Go tip, a simple "make" on the golangci-lint never success in my experiences.

This changes fix all the output reported by the revive and shadow.

The unordered list item with hyphen ('-') cause too much confusion and inconsistency, nevertheless most of still use it.

Case one, given the following markup,

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 [1].

[1] https://docs.asciidoctor.org/asciidoc/latest/lists/unordered/#basic-unordered-list

Previously, in the htmlWriteBlockQuoteEnd, if attribution is set we add HTML tag <div> and close it later after we add citation.

The issue is we did not check if attribution is true again when we add closing tag for div, which make the div above of blockquote get closed.

Given the following markup,

The list on item 2 now start with <div class="ulist circle">.

Given the following adoc,

If we call ToHTMLBody, the output is

This changes remove the empty line at the top.

Previously, if we have block image in paragraph, we parse it as inline image but with invalid src, for example

would be parsed as <img src=":imy.png" alt="multi line">. This is incorrect according to asciidoctor output.

By default the last-update-label value set to "Last updated" and the value is the document modification time.

If the label is suppressed with "!", no "Last updated" will be print on the footer.

The inline passthrough "pass:" can be used to control the substitutions applied to a run of text.

Ref: https://docs.asciidoctor.org/asciidoc/latest/pass/pass-macro/

Macro footnote grammar,

In asciidoctor, footnote can be placed anywhere, even after WORD without space in between.

The REF_ID, define the unique ID for footnote and can be used to reference the previous footnote. The first footnote with REF_ID, should have the STRING defined. The next footnote with the same REF_ID, should not have the STRING defined; if its defined, the STRING is ignored.

The meta tags from original asciidoctor are ordered as viewport, generator, description, keywords, and then author.

While at it remove empty style tag due to when testing we use empty.css not "stylesheet!".

Previously, given the following include statements in the main document

Where list_desc.adoc content is,

The first include is parsed correctly, but the second include is parsed as is.

Using string literal for testing string input that may contains backtick or double quote make the test code become unreadable and hard to modify.

The test.Data help this by moving the input and expected output into a file that can we write as is.

This update fix some issues related to new line on test.Data.

Previously, we always set the ID prefix and separator default to "_" if its not set, this cause all of the ID is prefixed with "_".

This changes use strict rules when generating ID following the Mozilla specification [1] and latest AsciiDoc Language [2].

The idprefix must be ASCII string. It must start with "_", "-", or ASCII letters, otherwise the "_" will be added to the beginning. If one of the character is not valid, it will replaced with "_".

The idseparator can be empty or single ASCII character ('_' or '-', ASCII letter, or digit). It is used to replace invalid characters in the REF_ID.

[1] https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id

[2] https://docs.asciidoctor.org/asciidoc/latest/sections/id-prefix-and-separator/

The order of meta names are "author", "description", "generator", and then "keywords".

Previously, to get list of author names, we need to iterate each of the Authors field.

This changes set the Attributes "author_names" to list of author full names, each separated by comma.

The generator metadata contains the library name and its current version.

This is to minimize memory allocation when using asciidoctor.

Previously, to test parser and check the generated HTML, we write AsciDoc input and expected HTML output using literal string …​. The text of input and output sometimes long, take multiple lines, which makes the test code ugly, hard to write, and read.

Using lib/test.Data we can write the input and output as the AsciiDoc markup and the HTML markup as is, simplify writing the test and more readable.

Given the following asciidoc check box markup,

It will rendereded as "❏ bc" instead of "❏ abc".

Both of those functions has been deprecated.

Since the Title function is to convert the adminition string into a human title (first letter uppercase), we can use a function to do that. Any unknown admonition will be returned as is.

Previously, when parsing cross reference we assume that if the string contains upper-case letter then it’s a label so we store it as title to search for ID later.

The bug is when ID is set manually and its contains upper-case for example "[#Id]".

This changes fix this issue by storing cross reference first, not assuming it as ID or title, and then when doing rendering we check whether its ID or title.

According to XML spec [1], the colon is allowed as the first and the next character. While period is only allowed on the next characters.

[1] https://www.w3.org/TR/REC-xml/#NT-Name