---
title: "Authoring with Markdown in Jekyll versus Authoring with DITA in OxygenXML"
date: 2015-03-26
description: "Jekyll versus DITA   1.0 Check out Ed Marsh"
canonical_url: https://idratherbewriting.com/2015/03/26/misconception-markdown-is-more-limiting-than-dita-jekyll-versus-dita/
---
# Authoring with Markdown in Jekyll versus Authoring with DITA in OxygenXML
To an extent, yes, Markdown itself is more limiting than DITA. But Jekyll doesn't just process Markdown on a page -- you can write in Markdown, HTML, Liquid, or JavaScript. With these options, you have a lot of freedom and flexibility -- even more so than DITA.

## What is Markdown

Markdown is a lightweight syntax (like a wiki syntax) used for generating HTML. A lot of platforms have Markdown processors (like Redcarpet and Kramdown) that convert the Markdown syntax into the appropriate HTML tags.

Because Markdown isn't standards-based, there are many different flavors or dialects of Markdown. Whereas DITA was agreed upon [by a committee](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita) and standardized, Markdown was created by [John Gruber](http://daringfireball.net/), a blogger, who wanted a faster way to create HTML.

Since Gruber's release of Markdown, there are at least a dozen different variants of Markdown, usually created when people need some syntax that isn't available in [Gruber's initial Markdown](http://daringfireball.net/projects/markdown/). Gruber wanted to keep Markdown simple rather than extending it with more robust syntax.

Although Jekyll processes Markdown, it also processes HTML. You can start a new Markdown file and begin typing in Markdown, and as soon as you run into a situation where Markdown syntax doesn't cover what you're trying to do (for example, figure captions), you can start using HTML. Then when you're done with your HTML syntax, you can switch back to Markdown — all in the same file.

Note that while you can put HTML tags inside of Markdown syntax, you can't put Markdown syntax inside of HTML tags. For example, if you surround a Markdown table with HTML div tags, you must use HTML syntax for the table because it appears inside of the HTML tags.

However, if you don't surround your table with HTML div tags, you can use Markdown syntax for the table, and inside the table, you can use HTML tags (such as to add a span tag to something in your table row, for example).

Note that table syntax isn't in the original Gruber Markdown. It was added by others with later variants. Probably the most common Markdown syntax is [Github-flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). With Github-flavored Markdown, you can use a syntax for tables, fenced code blocks, and other elements.

When someone says Markdown is too limiting, we really have to extend this to say Markdown + HTML is too limiting, because most processors that process Markdown also process HTML in the same file.

## Jekyll and Liquid

Along with Markdown and HTML in pages, Jekyll also processes a templating language called [Liquid](https://docs.shopify.com/themes/liquid-documentation/basics). Liquid was created by Shopify in part to populate e-commerce sites with product information.

Liquid has common themes from the programming world, such as variables, if-else statements, for loops, and other logic. I'll provide more examples of Liquid in some upcoming posts. But you can use Liquid in a Jekyll page right alongside your Markdown and HTML.

## Semantic tagging

One objection is that DITA provides *semantic* tagging for your content, so you're not just creating div soup, but you actually have semantic meaning associated with the elements.

This may have been more true in the past about HTML, but HTML5 introduces a lot of semantic tags. For example, it provides [new elements](http://www.w3schools.com/html/html5_new_elements.asp) such as `section`, `summary`, and `aside`. You can leverage all of these tags in your Markdown/HTML pages and Jekyll templates.

XML provides more flexibility with elements, since you can create your own elements and map them to anything you want in your transform stylesheet. Many people say this allows XML to address any potential format that might come along. You just adjust your stylesheet to transform an XML tag into the desired tag for your output, and you're all set.

At first this seems really cool, but I always found that HTML was my primary output. It wasn't very efficient to wrap all my content in a neutral storage container (XML) and then convert all those tags into specific HTML tags. If HTML is the primary output, why not just work directly in HTML syntax?

Except for PDF, most platforms process HTML. Even with PDF, you can use tools such as PrinceXML to convert HTML into PDF using CSS (rather than XSL-FO). You can also convert Markdown into PDF, epub, mobi, and more through [gitbook.com](https://www.gitbook.com).

If you're using DITA primarily to transform content to HTML, the semantic tagging argument begins to feel hollow, because regardless of the semantic nature of the DITA tags, they all get transformed to HTML tags in the HTML output.

If your DITA task contains `result` and `example` and `postreq` and elements, or maybe `prereq` and `context` elements, these just get transformed into standard HTML tags, such as `p`. It depends on how your XSLT stylesheet maps the DITA elements to HTML tags, but at the end of the day, your output will be limited by the tags in the target output.

Although you may have 330 DITA tags, when you push to HTML, your 330 DITA tags become at most [128 HTML tags](http://webdesign.about.com/od/html5tags/l/blhtml5reference.htm), because this is how many tags are in HTML. Specialize all you want with your custom semantic tags -- they become `p` and `li` and so forth when you output to HTML.

Back when I was using DITA, at some point I realized that steps in `task` elements and lists in regular `topic` topics both output to `ol` and `li` tags, so I just started using regular topics instead of tasks. And all the deliberation about using `info`, `tutorialinfo`, or `stepresult` after a `cmd` element in a `step` becomes pointless when they all transform to `p` in the HTML output.

Beyond the 128 HTML tags, HTML provides its own method for expansion. You can create custom classes and IDs to your heart's content and define the look and feel of each element however you want.

In DITA, you can add `outputclass` and `id` attributes to an element in the same way, but sometimes the Open Toolkit (the code that transforms DITA into various outputs, such as HTML) does some unexpected things with the ID tags. For example, when you add an `id` tag to a `section`, the output prepends the `topic` ID before each section ID.

If the IDs shift in the output, this can complicate JavaScript triggers that depend on specific IDs (such as show/hide tags to collapse or expand section elements).

## Element order requirements

Another aspect of DITA authoring is not just elements, but element order. Although you have 330 DITA elements, you can only use the elements in certain orders. For example, a `step` can only appear inside a `task`, and so forth.

Although HTML also enforces some order with the elements (for example, an `li` tag must be used inside an `ol` or `ul` tag), DITA takes element order to an entirely new level. Much of the enforced element order is designed to support information typing. Information types are enforced patterns that are designed to fit common information structures.

The enforced element order for DITA restricts the supposed freedom and flexibility of having so many elements available. You may find, after finishing a list, that you actually only have a few options — a `result`, `postreq`, or `example` element.

![options_dita](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/options_dita-550x352.png)

You can extend your options if you specialize, meaning if you extend the DTD schema to introduce your own tag orders and information types. But specialization is a lot of work and most people don't do it. One easy workaround is to use a `p` or `ph` tag with an `outputclass` attribute as a workaround. (This is essentially a lazy way to do divs and spans for custom tags in DITA.)

When I was authoring with DITA, I found the tag orders that enforced information typing to be really restrictive -- I often had to resort to workarounds. For example, you would think you could create subheadings (`h3` elements) in DITA without nesting entire `concept` or `task` structures inside each other (like Russian dolls), but you can't because the committee that defined the `concept` information type decided not to allow subheadings except through nested `concept` elements in the DITA DTD.

Why were subheadings restricted? I think subheading elements were restricted because of DITA's emphasis on extensibility. *Theoretically*, your information is a bunch of chunks that you can mix and match in any order and arrangement you want.

If you insert a `section` element, DITA can render it as an `h2` or `h3` dynamically based on its placement in the DITA map's TOC hierarchy. It can only render it on the fly as `h2` or `h3` if it is a generic `section.`

This dynamic heading level rendering is one feature that you can't do in Markdown/HTML when you start using `h2` or `h3` tags. In Jekyll, if you create a chunk that has an `h2` heading, when you include it on a page (using `includes`), it will always have an `h2` heading.