Variables and conditional processing in Jekyll versus DITA

by Tom Johnson on Mar 26, 2015
categories: dita • jekyll

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.

First, in your configuration file, define the variable:

audience: Mac

Now use an if-else statement like this on the page:

{% if site.audience == "mac" %}
Your MacBook Pro is going to make you so happy!
{% elsif site.audience == "pc" %}
Thanks for supporting the dying PC industry.
{% else %}
Congratulations on the purchase of your new computer.
{% endif %}

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:

<ul>
 {% for page in site.pages %}
   {% for tag in page.tags %}
       {% if tag == "getting_started" %}
           <li><a href="{{ page.permalink | prepend: site.baseurl }}">{{page.title}}</a></li>
        {% endif %}
   {% endfor %}
 {% endfor %}
</ul>

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:

---
title: My Page
permalink: /my_page_link/
tags: getting_started
---

DITA doesn't have any equivalent to either tags or a for loop. Take a look at some of these other tags available through Liquid to get a sense of what's possible.

How you do variables and conditional processing in DITA

In DITA, you don't have variables. Instead you would use a keyref, which you define in the ditamap file like this:

  <keydef keys="dog_name">
    <topicmeta>
      <keywords>
        <keyword>Fred</keyword>
      </keywords>
    </topicmeta>
  </keydef>

To access the dog_name, you would write something like this:

I have a wonderful dog named <keyword keyref="dog_name"/>.

Suppose you have three different outputs. You could create different attributes on the keyword element, like this:

  <keydef keys="dog_name">
    <topicmeta>
      <keywords>
        <keyword product="product_a">Fred</keyword>
        <keyword product="product_b">Jack</keyword>
        <keyword product="product_c">Spot</keyword>
      </keywords>
    </topicmeta>
  </keydef>

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:

<?xml version="1.0" encoding="UTF-8"?>
<val>
    <prop action="exclude" att="product" val="product_b"/>
    <prop action="exclude" att="product" val="product_c"/>
</val>

Now to do the conditional processing in DITA, you add attributes to the elements:

<p audience="mac">Your MacBook Pro is going to make you so happy!</p>
<p audience="pc">Thanks for supporting the dying PC industry.</p>
<p>Congratulations on the purchase of your new computer.</p>

See Conditional Profiling for more details.

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.

Next: 1.3 Creating re-usable chunks (conref) in Jekyll versus DITA

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.