About this Blog

This section contains several post around the context of documentation.

This Blog is written with asciidoc and the target formats (a static web site, Confluence Pages, simple HTML, …​) are generated with the docToolchain.

In order to get the structure generated as it is, you need to follow some rules

  • Images to include should be stored within the asset/images folder

  • For each year there is a folder where you can put your posts for the corresponding year

  • To get the years ordered descending, ever index.adoc of a year includes the jbake-order attribute counts down from 99 (year 2023 got 99, year 2024 got 98, and so on)

  • Every post file must start with the prefix BLOG_

  • Every post must start with the following header:

    Header of one Post
    :jbake-title: _The title of the post_
:jbake-author: _Author of the post_
:jbake-date: _date of the post in the format yyyy-mm-dd (e.g. 2024-05-03)_
:jbake-type: post
:jbake-tags: _comma separated tags_
:jbake-status: published
:jbake-menu: Blog
:jbake-order: _Order number for the post; the ordering is ascending_
:keywords: {jbake-tags}
ifndef::imagesdir[:imagesdir: ../assets/images]

ifndef::optimize-content[]
:toc:
endif::optimize-content[]

== {jbake-title}
ifndef::optimize-content[]
{jbake-author}
{jbake-date}

Keywords: {keywords}

---
endif::optimize-content[]

    You can copy the .template.adoc to the corresponding year and start posting.

One word of why one blog post file must start with the prefix BLOG_

We like to generate this blog section to all formats, not only to the static website. So, we even want to publish this section to Confluence.

At least for having simpler configuration possibilities for the docToolchain task publishToConfluence, it’s easier to have one adoc file which includes the corresponding ones.

Of course, it’s not convenient to change the index.adoc file whenever you need to include a new blog post to the site.

Luckily docToolchain provides a task called collectIncludes which crawls over your directory structure for files with the name matching to the pattern ^[A-Za-Z]{3,4}[_].* (like for BLOG_xxxx.adoc or ADR_xxxx.adoc) and creates one …​includes.adoc file within the build/_includes folder. This file can then be included wherever you want to include the matching files. For detailed infos, check the documentation of the task. In short: we use this technique within our CI pipeline in order to generate the needed targets by adding

ifndef::optimize-content[]
include::{targetDir}/_includes/BLOG_includes.adoc[]
endif::optimize-content[]

into the index.adoc file of this section.