Set up Jekyll with Asciidoc

This is my first attempt to create a personal website (and more specifically a blog) using Jekyll.

My last blogs were using solutions like Wordpress or blogspot, but it’s been a while that I found they were totally not the good solution if I wanted to create a dev blog : syntax highlighting is not available (or to clumsy to set up), formating is too basic with the WYSIWYG editor, etc. I needed a solution more open to customizations that could bring me syntax highlighting out-of-the-box.

Last year I discovered Asciidoctor and Antora. Before that I used mostly Markdown that I liked for its simplicity. Asciidoc is a Markdown++. It offers more possibilities which makes it a good choice to write technical docs and …​ Found it could be a good opportunity to find a static blog engine that could use Asciidoc instead of Markdown (because yes, most of static website generator are more Markdown-friendly and almost none is available natively for Asciidoc).

I liked the simplicity of Jekyll, and found out an extension is available to write articles in Asciidoc : it’s worth a try!

The main documentation is available on the project Github page. The first thing you see is that the installation seems pretty …​ long!

I also found an easier way on this site.

So my first attempt was to include gem 'jekyll-asciidoc', which was easy to set up. The first generation was OK, but the look of the generated Asciidoc looked too awful. I needed something more like the new version Antora (at this time of writing, version 3 is still in beta, but the look is way better that the default Asciidoctor style). I wanted something like this : with good looking admonitions, a modern font, etc…​

I found out that the style I wanted was available here. So I imported these CSS, made some customizations (paths of resources), integrated the required fonts, made some style changes here and there to avoid compatibily problems with the default minima Sass file (I won’t go into details here).

And voilà, here are some examples :

Title 2

Title 3

Title 4

• item 1

• item 2

• item 2

1	bla
2	bla2
3	bla3

CPU

The brain of the computer.

Hard drive

Permanent storage for operating system and/or user files.

RAM

Temporarily stores information the CPU uses during operation.

Keyboard

Used to enter text or control items on the screen.

Mouse

Used to point to and select items on your computer screen.

Monitor

Displays information in visual form using text and graphics.

Links : https://www.asciidoctor.org

After landing the cloaked Klingon bird of prey in Golden Gate park:

Everybody remember where we parked.

— Captain James T. Kirk
Star Trek IV: The Voyage Home

Syntax highlighting is done using pygment as explained in the doc. I also made some customisations on callouts to make them look more like the Spring documentation.

package examples;

public class ExampleBean { (1)

    // Fields omitted

    @ConstructorProperties({"years", "ultimateAnswer"}) (2)
    public ExampleBean(int years, String ultimateAnswer) {
        this.years = years;
        this.ultimateAnswer = ultimateAnswer; (3)
    }
}

1	something
2	something else
3	another thing

example with JSON

{
    "employee": {
        "name":       "sonoo",
        "salary":      56000,
        "married":    true
    }
}

Another example numlines

1
2
3
4
5
6
7
class ExampleBean {
    // comment
    lateinit var beanOne: AnotherBean
    lateinit var beanTwo: YetAnotherBean
    /** another comment */
    var i: Int = 0
}

Graphviz were also implemented using this doc.

Equations are also available (see this link).

Example of equations

\(\sqrt 4 = 2\)
\(C = \alpha + \beta Y^{\gamma} + \epsilon\)

This is a numbered equation \eqref{myequation}

\[\begin{equation}\label{myequation} c^2 = a^2 + b^2 + 5 \end{equation}\]

Example 1. Example of custom HTML

example of passthrough tag

Admonitions :

this is awful!

hello

ce truc est super-important!!

warning

note !!

avec un emoji ! ! et un coeur :

Bold and Italic and Code text.

Texte replacement : ©, →, ⇒, ™

Table needed some adaptation (conflict with minima styles)

Table 1. Table Title

Column 1, Header Row	Column 2, Header Row
Cell in column 1, row 1	Cell in column 2, row 1
Cell in column 1, row 2	Cell in column 2, row 2

I know some items are not perfect and need some slight improvements but things are ready for the first articles!