AsciiDoc for Hugo QuickRef

AsciiDoc for Hugo

AsciiDoc is a markup language, and it is also the name of the initial text processor implementation that renders the plain-text content to a variety of output formats like HTML, PDF, TeX, Unix manpages, e-books or slide presentations. AsciiDoc was created in 2002 by Stuart Rackham, a Ruby implementation of the text processor called ‘Asciidoctor’ was released in 2013 and is widely used for example by GitHub and some of O’Reilly’s books and e-books.

The AsciiDoc format can be used by hugo for content creation, this post gives a short overview of some of the most common markup tags to be able to write some content for hugo.

Headings

The 'title' value from the hugo metadata section is turned into a <h1> tag when rendered as html. This means we should use level 2 for the section headings of a post.
Headings are simply preceded with the appropriate number of equal characters (=) at the beginning of a line:

Paragraphs

Paragraphs in AsciiDoc are just one or more lines of consecutive text, newlines in the source are not preserved.
Starting a paragraph can be done by inserting at least one blank line between two sections of text. Using a blank followed by a plus ( +) at the end of a line will insert a hard line break, which means a <br/> tag when rendered to html.

first line
second line

new section +
with linebreak

Block formatting

a block of code is marked at the beginning and end with four minus (----) characters, before the block you can add some style information.

.some java code
[source,java]
----
class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}
----

class HelloWorldApp {
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}

.some xml code
[source,xml]
----
<section>
  <title>Section Title</title>
</section>
----

 <section>
   <title>Section Title</title>
 </section>

Inline formatting

Simple markup can be used for formatting single words or parts of words and sentences.

Lists

Lists use asterisk (*) or minus (-) to mark the single items. A new list level is created by using multiple asterisks or for each unique marker encountered.

- item 1
- item 2T22:27:53+02:00
* item 3
* item 4

* item 1
* item 2

.this is a simple title for the list
* level 1
** level 2
*** level 3
** level 2 again
* level 1 again

Tables

Tables start with a header defining some properties, then the table cells and an end marker:

[%autowidth.stretch, options="header"]
|=======
| header1 | header2 | header3
| cell a | cell b | cell c
| cell d | cell e | cell f
|=======

Comments

Large comments can be marked with //// at the start and end, the content will be completely ignored for rendering.

////
Big ol' comment
sittin' right 'tween all those text
y'all ain't seeing it when rendered
////