In the previous post, I compared writing in Markdown versus writing in XML. In this post in the series, I want to look at variables and conditional processing between the two platforms.

Variables in Jekyll

In Jekyll, you can assign a variable a specific value, like this:

{% assign dog_name = "Fred" %}

Now you can use {{dog_name}} in your content and it will say Fred in the output:

I have a dog named {{dog_name}}.

Although you could assign this variable directly on your page, it's more common to put the variable in your configuration file. Each Jekyll project has a configuration file where you define your project settings and other build details.

The configuration file is written in YML syntax, so you just add a key-value pair somewhere in the file like this:

dog_name: Fred

In a single sourcing scenario, you would have a separate configuration file for each output. On your page, you access that variable in the configuration file with the site namespace, like this:

I have a wonderful dog named {{site.dog_name}}.

Now if I have 3 outputs, and I want my dog's name to change for each output, I create 3 separate configuration files. In each configuration file, I assign a different value to dog_name. When the site builds, it will use the name assigned in the configuration file.

Conditional processing in Jekyll

That's how you would do a simple variable, but what about conditional processing? Suppose you have some content on the page appropriate to a one audience, and other content appropriate to another audience. And the page is common to both outputs.

When you build with the configuration file where the audience value is mac, it will say, "Your MacBook Pro is going to make you so happy!" And when you build with the configuration file where the audience value is pc, it will say, "Thanks for supporting the dying PC industry." If the configuration file doesn't specific either mac or pc, it will just say, "Congratulations on the purchase of your new computer."

You can get a lot more sophisticated with the logic, combining if-else statements with variable assignments, and much more. This is just a simple taste of what's possible.

For loops in Jekyll

Some of the Liquid logic takes you beyond what you can do with DITA. For example, suppose I wanted to show a list of all pages with a specific tag. I could use a for loop to do this directly on a Jekyll page:

This code would look through all the pages in my Jekyll project and find all those pages that have getting_started as a tag in the frontmatter, which is just some metadata at the top of the page. Here's what that frontmatter looks like:

Now you store these attributes in with your build logic. For example, in OxygenXML, you add them in the Editor > Edit modes > Author > Profiling/Conditional Text area. For the product attribute, you would add product_a, product_b, and product_c.

In OxygenXML, when you create a transformation scenario for an output (the equivalent of a configuration file in Jekyll), you associate a DITAVAL file that instructs the transformation to exclude elements with certain attributes.

Here's a DITAVAL file that filters out elements containing product attributes for product_b and product_c:

Conclusion

Both platforms allow variables and conditional processing in powerful ways. Conditional processing is certainly one of DITA's strengths, but you can do conditional processing in similar ways with Jekyll. And I must admit, the conditional processing seems a bit easier and more intuitive in Jekyll because you're using if-else statements. Variable assignments are much more straightforward as well.

I'm not trying to score the platforms against each other so much here. I mainly want to say, hey, you can do the same things you're doing with DITA using Jekyll. Technical writers don't have to limit themselves to tech-comm platforms to do conditional processing and single sourcing.

Stay current with the latest in tech comm

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers