Roles

Software Developer, Information Architect

Skills

Jekyll, Ruby, CSS, JavaScript, Metalsmith, LiquidJS, NodeJS, Travis, CI/CD, Git, Support, Training

When writers needed a way to reuse their then roughly 500 markdown topics across multiple products, I provided a method of authoring in Jekyll to support conditional coding in markdown. Writing with conditional coding can be messy regardless of the authoring method used, but with Jekyll, they were happy to be able to continue editing in markdown rather than migrating to DITA. Three years later, they are still happy with the conditional coding method, which is now provided by a Metalsmith and LiquidJS solution I wrote. The change was to address the need to deliver marked-it-cli markdown to the corporate build and translation workflow rather than deliver the output HTML files that Jekyll produced.

IBM Cloud products started adopting markdown in roughly 2015 for content authoring. IBM Watson Studio was one such product. By the end of 2017, its documentation source contained a number of markdown topics that conformed to IBM Cloud markdown standards (GitHub-flavored markdown with some Kramdown extensions, transformed to HTML with the marked-it-cli parser).

Starting in 2018, Watson Studio cloud product features were added to various on-premises products. Much of the functionality and UI would remain consistent, which resulted in the need to reuse much of the existing topic content. Problem is, reuse is difficult when you can’t conditionalize the content by product.

That’s where a static-site generator (SSG) like Jekyll comes in. With an SSG, you can write simple code like this to filter content:

{% if site.product == "cloud" %}
Paragraph targeted to cloud audiences.
{%- endif %}
{%- if site.product == "onprem" %}
Paragraph targeted to on-premises audiences.
{%- endif %}
{%- if site.product == "local" %}
Paragraph targeted to desktop application audiences.
{%- endif %}

Jekyll was the SSG of choice for a couple of reasons:

• It supports Kramdown, which is similar to IBM Cloud markdown, making migration painless.
• It is one of the oldest and most stable SSGs out there. It has a large community.

As an SSG, it offered additional benefits, too:

• Live preview of the filtered output while authoring
• Includes, which provide authors with shortcuts for long repeated HTML snippets, such as video embeds
• Templating, which allows for a different style to be applied to the output for each condition—perfect for the three documentation apps at the time: IBM Knowledge Center, Analytics product hub, and the Data Platform documentation service

To use Jekyll, however, I needed to be address a few of things to ensure the new writing method worked with the IBM Knowledge Center build processes, such as writing the logic to read YAML ToC files recursively and create a set of ditamaps for publishing. I also added features to provide the writers with a delightful and effective authoring experience, such as custom styles to highlight internal, beta, and draft content in the local table of contents and topics to ensure markup was appropriately applied.

After I provided a workshop to educate folks on the new system and how to set up the custom builds on TravisCI to publish, we started on the journey, and the team is still authoring conditionally coded markdown today in 2023 in their current library of 1,200 topics, albeit with Metalsmith.

For reasons previously mentioned, I did replace Jekyll with Metalsmith, which is a highly customizable SSG. It allowed me to modify the custom pre-processor with the latest LiquidJS templating language to preserve the Liquid coding of Jekyll. It also allowed me to create a transformer that used marked-it markdown instead of kramdown. And, I was able to replicate the required configuration variables and local development environment, similar to those with Jekyll. Thankfully, Metalsmith provided the added benefits of building the content five times faster and working in a NodeJS environment, which is easier for the team to work in than Ruby.