RSS

Creating a technical Website with Hugo and Asciidoc

Creating a technical Website with Hugo and Asciidoc

2020 10 01 head

I hosted my technical blogs on blogger for years. If I correctly remember I started to use blogger ten years ago. It is a great tool with some drawbacks. Over the years the drawbacks sting more and more:

  • Their editor is brittle, with limited functionality and unreliable. The generated HTML is not legible and does not support concepts such a micro fragments, meta information or simple functions such as source code highlighting.
  • The last quarters they started to tinker with their editor and output format. My older posts are now a mess and can only be open in HTML mode. If I switch to their WYSIWYG editor the layout is destroyed and random fonts family and sizes are displayed. Worse the blogs are also displayed mangled to the readers even if I do not edit them. This destruction of all older blogs and the missing migration path were killer criteria.
  • Blogger does not support modern markup language such Markdown or Asciidoc. Blogger uses a proprietary and not easy to port format.

It is time to find an alternative, and I have to confess I am a huge fan of Asciidoc.

OK, so why not go with Markdown? Don’t get me wrong, there is nothing bad with Markdown - except that no one should probably use it when Asciidoc and Asciidoctor are available. I’m writing all my documents with Asciidoc.

The following needs are identified:

  1. I shall write blogs with the selected solution. The blogs shall be written in Asciidoc. The blog platform should support multiple years of publishing and referencing between blogs. Our projects and our collaborators put effort to regularly publish articles.
  2. I shall be able to write technical articles and publish them on the same site. The articles are naturally written in Asciidoc. We want a professional looking documentation to encourage new users to try our open source components.
  3. I shall publish the technical documentation of the open source components I develop on the same site.

Hugo was selected as static site generator because its support for Asciidoc is tremendously improving.

First I used the hugo-theme-techdoc to customize Hugo. It worked great for the technical documentation and technical articles but fall short of my wishes for the blog part. When I discover the theme Docsy. It supports the technical documentation, technical articles, and blogging.

The best part is that Hugo now supports Asciidoctor natively. No more strange manipulation to load gem modules you need. And diagrams through asciidoc-diagram and plantUml are generated in the expected folders. The documentation is still on the light side but you find the needed information in the various pull requests.

The bonus is that Asciidoctor newer versions have native support for rouge syntax highlighter. It is no more necessary to load pygment highlighter and configure CSS files. Another huge gain is that plantuml and other diagrams are generated at the right location.

Install the Tools

My development platform is a MacBookPro and MacOS. I use Homebrew as a package manager.

The instructions to install hugo and asciidoctor are:

brew install hugo                         1

brew install asciidoctor                  2
gem install asciidoctor-diagram
gem install asciidoctor-rouge
gem install asciidoctor-html5s
gem install asciimath

brew install plantuml                     3
brew install graphviz

sudo npm install -D --save autoprefixer   4
sudo npm install -D --save postcss-cli
sudo npm install -D --save postcss
  1. Install hugo application
  2. Install asciidoctor and additional asciidoctor packages
  3. Install plantuml and graphviz for diagrams, in particular UML sketches
  4. Install PostCSS and additional packages used by docsy to generate deployment site. See also docsy documentation.

Asciidoctor Configuration

Below the configuration of asciidoctor in the config.toml file.

[markup.asciidocext]
  extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
  workingFolderCurrent = true
  [markup.asciidocext.attributes]
    imagesdir = "../pics"
    source-highlighter = "rouge"            1
    rouge-style = "github"                  2
    rouge-css = "style"                     3
    icons = "font"                          4
    ref-less = "https://less.works/[LeSS]"  5
  1. Select rouge as source highlighter. You should not add it to the extensions because since Asciidoctor version 2.0 rouge is included.
  2. Define the style used to highlight source code.
  3. Configure rouge to generate all formatting data into the generated html file, avoiding any css file configuration.
  4. Icons provide better looking icons for various Asciidoc} constructs.
  5. Define document attributes which are accessible to all processed documents (DRY concept for the whole site).

Docsy Configuration

Add First Level Folders

Each time you add your own first level folder - meaning at the same level as docs, blog, about, or community you need to extend the layout to support it. For example, I store technical articles in the folder ideas and use the standard template. So I need to add (if not, no items are visible in the side bar).

cp -R ./layouts/docs ./layouts/ideas
Change layouts

We had to change the partial footer.html to display a better looking copyright clause. The original version has hard coded text not really compatible with the commons creative license we are using. The layout is updated by overwriting the involved partial file.

cp $prjDir/src/site/website/docsy/layouts/partials/footer.html $siteDir/themes/docsy/layouts/partials

Enable Local Search Engine

One cool feature of Docsy is local search support through lunrjs engine.

algolia_docsearch = false

offlineSearch = true
offlineSearchSummaryLength = 200
offlineSearchMaxResults = 25

Learning

The static website is published under Open Source Components.

The source of the whole website is available under Website Source Code.

Printing of a single article is supported through your browser. You can configure printing a whole section with or without a table of contents through configuration options. For advanced cases you can define the layout of the printed document.

You can use relative links in your Asciidoc documents. Beware where the file are located by Hugo engine and the naming conventions shall follow Hugo rules.

Funny is that the blogger software and the docsy theme are from the same company Google.

This blog article is naturally written in Asciidoc syntax.