A Tiny Subset of Asciidoc for Blogging

As promised in my earlier post on why I decided to build my own Shitty Static Site Generator, I’ll explain the markup format that I use for the posts on this site. The goal was to find a subset of Asciidoc that would be easy to parse myself, but would still result in valid documents, so that they can be processed by all other tools that understand Asciidoc without any problem. For instance, I wanted the syntax coloring in my editor to ‘just work’.

In order to achieve that, I selected the following parts from the Asciidoc specification. They are categorized by the types of elements as they are used in a HTML page:

Everything that is not described below will not work. I may add new stuff in the future, if I feel it is needed. If I do so, I will update this page.

A header consists of the title of the post and various fields of metadata. It looks like this:

= An Example Post
Erik Winter <info@erikwinter.nl>
2020-12-01
:kind: note
:language: EN
:project: shitty-ssg
:tags: asciidoc, ssg, parser
​

It starts with the title on the first line, which is prefixed with =, and it ends with an empty line.

A the attributes of a post are defined as a key-value pair. Each pair gets its own line. The following attributes are supported:

Author and publishing date are the only two lines that don’t start with a semicolon. If the line has the format YYYY-MM-DD it is assumed to be the publishing date, the rest is considered the author. That last value is not used on this site, but useful for other tools.

Lines that are not recognized are ignored. Later lines overwrite previous ones if they define the same thing.

Block Elements

A post constist of multiple blocks that are separated by a blank line. Currently the following blocks are supported:

Subtitle and Subsubtitle

== A Subtitle

Start with a ==, or a ===, followed by a space. They translate to <h2> and <h3> elements.

List

* List item one
* List item two
* List item three

Lists items start with an asterisk and are not separated by a blank line. The text of the item is parsed as a paragraph.

Code Block

​----
func (d *Dummy) DoSomething() string {
  return “No. I don’t want to.”
}

func (d *Dummy) SudoDoSomething() string {
  return “Ok. If you insist, I’ll put my objections aside for a moment.”
}
​----

Code blocks start and end width four dashes on an empty line. The text between is put in <code> tags and result in monospaced font with whitespace preserved. Empty lines are allowed.

Paragraph

A paragraph is a line of text that gets parsed to find inline elements.

Inline Elements

Currently the following types are recognized:

Strong and Emphasis

a text with some *strong* words, that I’d like to _emphasize_.

It is possible to combine the two for the same text.

Link

Check out this https://erikwinter.nl/[awesome website] now! 

Whatever is between the opening bracket and the first space before that is taken as URL, so both absolute and relative links without domain are possible.

Inline Code

Some text with `code` in it.