Applying structured data
Using controlled templates to write DITA and Schema.org compliant content helps us write more functionally.
Jekyll ensures as a great way for technical writers to generate topic based web content due to its templating function. Mixing DITA topic types and Schema.org together and using layout templates to generate the output prove a good method to apply structured data. For example, if we write a topic that we define as a concept, we create one concept.md template to write the content and then a corresponding concept.html layout to display the content. Within this concept.html layout, we can add DITA XML data or Schema.org metadata. When we generate the topic, our XML and structured data will appear in the metadata.
The two examples below show firstly a topic template concept.md. We'd use this as our key content template where we edit the actual text we want to appear. Secondly, the XML snippet concept.xml that we would insert into our final output via a Jekyll layout template. This would include DITA tags in our final output in the metadata. We would repeat this for Schema.org type information.
Using topic based authoring techniques coupled with structured data concepts ensure that our topics remain short and to the point.
Example
---
# concept.md
# This is a strict template for concept topics adapted
# from https://www.oxygenxml.com/dita/1.3/specs/archSpec/technicalContent/dita-concept-topic.html
layout: post # _layouts/concept.html
title: # required
summary: # required, text or markdown
conbody: # required, text or markdown
example: # text or markdown
---
<!-- concept.xml -->
<concept id="concept">
<title>{{concept.title}}</title>
<shortdesc>{{concept.description}}</shortdesc>
<conbody>
{{concept.conbody}}
<example>{{concept.example}}</example>
</conbody>
</concept>