I hosted my technical blogs on blogger for years.
If I correctly remember, I started to use blogger ten years ago. It was a good choice at that time.
I could easily write blogs and publish them.
It is a great tool with some drawbacks. Over the years, the deficiencies sting more and more
The major drawbacks are:
Their editor is brittle, with limited functionality, and unreliable. The generated HTML is not legible and does not support concepts such as micro fragments, meta information, or simple functions such as source code highlighting.
The last quarter, they started to tinker with their editor and output format. My older posts are now a mess and can only be open in the 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? Do not get me wrong, there is nothing bad with Markdown; except that no one should probably use it when Asciidoc and Asciidoctor are available. I am writing all my documents with Asciidoc [1].
The following needs are identified:
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.
I shall be able to write technical articles and publish them on the same site. The articles are naturally written in Asciidoc. We want professional-looking documentation to encourage new users to try our open source components.
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.
Static website generators have strong advantages for technical savvy people:
Hosting is cheap. GitHub, GitLab, or Bitbucket pages even host static websites for free.
The source files go into Git for backup and history.
The source files are in plain text:
Changes come in as a Pull Request for proper review and CI pipeline validation.
The sources are open in our IDEs, which encourages refactoring them alongside the code. This results in less stale content.
First I used the hugo-theme-techdoc to customize Hugo. It worked great for the technical documentation and technical articles but fell 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 need information on 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.
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-bibtex
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. |
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 a 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 concepts for the whole site). |
CAUTION
Newer versions of hugo have stricter security restrictions. You must explicitly enable asciidoctor support by adding the following statements in your configuration file
[security]
[security.exec]
allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$', '^asciidoctor$']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 sidebar).
cp -R ./layouts/docs ./layouts/ideasWe 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 creative commons 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/partialsThe 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 files are located by Hugo engine and the naming conventions shall follow Hugo rules.
Avoid the specialized but uncompleted html5s backend and use instead the html5 backend. I was not able to find good examples of stylesheets for the semantic backend. The html5s backend uses new names for classification and sometimes different HTML structures. The regular available stylesheets will not style correctly the generated website.
The Docsy theme does not explicitly support AsciiDoc documents and the associated stylesheets. I had to extend the Docsy stylesheets with styling for admonition blocks, quote blocks, and embedded images to improve the quality of the texts.
| The Hugo theme community is slow to better support AsciiDoc documents. The Hugo developers clearly stated that styling for AsciiDoc documents is the responsibility of theme authors. All Hugo users shall be aware that AsciiDoc is an officially supported input format. |
Funny is that the blogger software and the docsy theme are from the same company as Google.
This blog article is naturally written in Asciidoc syntax.
[1] Static Website Improvements Marcel Baumann. 2023.
[2] Improving a Static Website Build With Hugo and Docsy Marcel Baumann. 2021.
[3] Support Comments for Static Hugo Website Marcel Baumann. 2020.
[4] Creating a technical Website with Hugo and Asciidoc Marcel Baumann. 2020.