<oXygen/>
blog about Publishing DITA Content Using the MKDocs Web Site Generator.
As Radu explains, MkDocs is a static site generator that makes it easy to publish a documentation website from a folder of Markdown files. His post shows how to install MkDocs, create a new project, and publish a simple DITA map via an oXygen transformation scenario.
With Radu’s approach, the DITA map file is first converted to a Markdown file, which is exported to HTML and then transformed via an XSLT stylesheet to the YAML format that defines the navigation structure of the MkDocs site.
This works well enough for simple maps like the oXygen flowers
sample (and in cases where manual steps are acceptable), but there are a few constraints that limit the utility of this process in larger projects and automated publishing scenarios.
This post explores how to work around those contraints and add local search to the site using additional resources from the MkDocs ecosystem, which have improved significantly since Radu first proposed this workflow.
MkDocs is a great way to spin up a simple site from a handful of Markdown files, but there’s one limitation that can be a show-stopper in larger projects — you can’t nest topics in the navigation.
Out of the box, the MkDocs navigation only supports unlinked section headings (groups) and pages. There’s no way to nest pages that include editorial content in a hierarchy of parent/child link relationships.
Note that a section cannot have a page assigned to it.
Sections are only containers for child pages and sub-sections.
mkdocs.org/user-guide/writing-your-docs
This is fine for small doc sets with flat structures, but less suitable for deeper information hierarchies commonly modeled in DITA publications.
MkDocs can be configured to create navigation sections automatically based on the subfolder names in the docs
directory, but in typical DITA projects with folders like concept
, task
, and reference
, that might not be welcome or useful. Unless the source file structure was explicitly designed for the desired navigation structure, there’s little value in showing folders in the table of contents (ToC) in the navigation sidebar.
In DITA projects, maps facilitate abstraction and re-use and allow us to create multiple navigation structures from a single set of files, so binding the file structure to the ToC is often counterproductive.
Although the DITA specification includes the <topichead>
element to create a parent node in the hierarchy without a corresponding topic, it can be confusing if some links open topics, and others don’t.
Many teams and style guides discourage the use of topic heads to avoid unlinked navigation nodes. For a consistent experience, every navigation item should open a new page.
— So how can we implement this with MkDocs?
The Material theme for MkDocs is one of the most popular open-source themes for documentation sites, and the best-known MkDocs theme by far.
With over 200,000 downloads per month, the theme is widely used and well-maintained by Martin Donath (@squidfunk), who put thousands of hours into the project. The mkdocs-material repository has a long history of over 300 releases, and more than 5000 commits by nearly 250 contributors.
With support for 40-odd languages, the theme includes a broad range of documentation-specific features such as page ToCs, versioning, anchor links, and robust mobile support.
Many developers already use Material for MkDocs to build docs sites for their projects. Thanks to the Markdown export features in Jarno Elovirta’s Lightweight DITA plugin for DITA Open Toolkit, we can easily integrate content authored in DITA to sites like this without spending any money on proprietary portal software or services.
But how does this solve our ToC problem?
Material for MkDocs includes an option to enable section index pages, so if you have a topic that serves as a landing page for a group of related topics, you can link to the content from the navigation section.
Here’s an example based on the structure of the DITA Open Toolkit documentation:
theme:
name: material
features:
- navigation.indexes
nav:
- 'DITA Open Toolkit 4.0': 'index.md'
- 'Release Notes':
- 'release-notes/index.md'
- 'Release history': 'topics/release-history.md'
The navigation.indexes
option in the theme features
key enables the section index pages, so links to index
files in subfolders open the corresponding topics. In this example, the Release Notes entry in the ToC is linked to the contents of the release-notes/index.md
file, and the Release history topic appears as a child topic inside the Release Notes node.
— But as the name foretells, it only works for topics whose filenames are literally index
. You can’t use arbitrary page names as section landing pages. Links to folder/index.md
will work, but folder/other-filename.md
won’t.
A proposal was submitted to the MkDocs project to relax this constraint and allow any page name to be defined as a section index, but the maintainers were reluctant to add this implementation to the Material theme, or to MkDocs itself.
So what can we do?
Fortunately, in plugin-based ecosystems like DITA-OT or MkDocs, maintainers don’t need to support every edge case in the core project.
Those who need additional features can create custom plugins to extend processing without asking permission or increasing complexity for others who don’t need the extra code.
The mkdocs-section-index plugin was created based on the earlier proposal, and extends the Material theme implementation to enable section landing pages with arbitrary names.
To use the plugin, first install it via pip
:
pip install mkdocs-section-index
and then add it to the plugins
key in the MkDocs configuration file:
plugins:
- search
- section-index
With this setup, we can extend the previous example by linking to additional landing pages with other names:
nav:
- 'DITA Open Toolkit 4.0': 'index.md'
- 'Release Notes':
- 'release-notes/index.md'
- 'Release history': 'topics/release-history.md'
- 'Installing DITA-OT':
- 'topics/installing-client.md'
The Installing DITA-OT ToC entry now links as intended to /topics/installing-client/
.
This plugin replaces the section index pages feature from the Material theme, so we can remove that entry in the configuration:
theme:
name: material
- features:
- - navigation.indexes
We don’t want to maintain the navigation structure in the MkDocs configuration file by hand when it’s already in the DITA map. We can read it directly from the output generated by DITA Open Toolkit.
The Lightweight DITA plugin is already capable of converting the map structure to a format that can be used with Markdown-based publishing environments like GitBook or mdBook, which define the ToC structure in a SUMMARY.md
file.
To publish GitHub-Flavored Markdown and generate this file, use the markdown_gitbook
transtype:
dita --input=input-file --format=markdown_gitbook
With the SUMMARY.md
file from the toolkit’s GitBook output, there’s no need to define the navigation hierarchy in the MkDocs configuration file.
The mkdocs-literate-nav
plugin can read the GitBook summary file for the navigation. As before, we first install the plugin via pip
:
pip install mkdocs-literate-nav
then add it to the MkDocs configuration file, and tell it which file contains the ToC hierarchy:
plugins:
- search
- section-index
+ - literate-nav:
+ nav_file: SUMMARY.md
One of the main reasons so many teams publish their documentation with Material for MkDocs is that it includes client-side search.
Whenever the MkDocs build
or serve
processes run, the local search index is automatically updated to reflect any changes in the Markdown source files.
This setup provides a viable open-source alternative to commercial webhelp solutions, and may be all you need for your own docs server.
In contrast to online search solutions that require a network connection to query the index, the MkDocs search works completely offline, so it can be used to build sites for secure environments and other scenarios where network access is not available.
Note: The search feature is currently based on Lunr.js, but Martin Donath is revisiting this approach, and plans to improve the search features in an upcoming version of Material for MkDocs.
If you’d like to support Martin’s work on the project, consider sponsoring him on GitHub, or subscribing to the insiders version, which provides early access to new features, and helps secure the future of the project with a sponsorware release strategy.
If you’d like to see the results of the approach outlined in this article, I built a demo site using the contents of the DITA Open Toolkit docs.
The demonstration output is available on the GitHub project site at infotexture.github.io/ot-mkdocs-demo, and hosted in the GitHub repository at infotexture/ot-mkdocs-demo.
The content was generated from the DITA-OT 4.0.2 docs as hosted on the DITA Open Toolkit project website at www.dita-ot.org/4.0/.
The repository includes a basic continuous integration setup that automatically publishes any content changes via GitHub Actions. You can borrow this setup to automate your own MkDocs publishing processes.
Note: I published a similar demo with GitBook output a few years ago, but never got around to writing about it. If you’re curious, you’ll find the repository at infotexture/ot-docs-mdbook.
]]>The highlight of the presentation was the announcement of my new “DITA Bootstrap” plug-in for DITA-OT 3.2, which generates HTML5 output with a basic Bootstrap template that includes responsive grid layout, global navigation menu and a table-of-contents sidebar.
Since the initial release of the plug-in, DITA-OT 3.3 has been released with new attribute sets that simplify these sorts of customizations to the default HTML5 output.
Where the old version required over 50 lines of code to override several templates, the new version of the DITA Bootstrap plug-in achieves the same result in 8 lines that add a few custom classes to the default attribute sets.
With the new plug-in version, the Bootstrap references have been updated to use the latest version of the framework (4.3.1), which includes significant enhancements to responsive design components, flexbox support, an improved grid system, and new Sass variables that simplify theming.
You can install DITA Bootstrap from the plug-in registry at dita-ot.org/plugins with the dita
command:
dita --install net.infotexture.dita-bootstrap
Specify the html5-bootstrap
format when building output with the dita
command:
dita --input=path/to/your.ditamap --format=html5-bootstrap
The plug-in includes a default static navbar with a project name and global links. To override the global navigation with a header of your own, pass a custom header file to the dita
command via the --args.hdr
parameter:
dita --input=path/to/your.ditamap --format=html5-bootstrap \
--args.hdr=path/to/your-header.xml
The plug-in includes a sample header alternative with a dark navbar.
Edit a copy of this file to adjust the content of the global navigation.
The plug-in includes a basic placeholder for custom CSS styles. You can edit this file to add style rules of your own, or override it by passing a custom CSS file to the dita
command via the --args.css
parameter:
dita --input=path/to/your.ditamap --format=html5-bootstrap \
--args.hdr=path/to/your-header.xml \
--args.css=path/to/your.css
For more extensive customizations, you may want to fork the repository and create a new plug-in of your own.
]]>Today the members of the OASIS Darwin Information Typing Architecture (DITA) TC announced the publication of the second version of their Committee Note “Lightweight DITA: An Introduction”:
Lightweight DITA (LwDITA) is a simplified version of the Darwin Information Typing Architecture (DITA). In comparison to DITA 1.3, it has a smaller element type and attribute set, stricter content models, and a reduced feature set. It also defines mappings between XML, HTML5, and Markdown so that authors can collaborate and publish across different markup languages.
In the references section, the Committee Note links to Marking Down DITA, my 2015 article on the rise of Markdown as an alternative input method for DITA projects.
As I wrote later in DITA-OT³ Markdown Support:
That post provided background information for people who are new to the concept of lightweight markup languages and how they relate to more structured authoring formats like DITA.
— But that was years ago, and a lot has happened since then…
At this year’s DITA Europe conference in Berlin, I gave a follow-up talk that explained how DITA Open Toolkit 3.0 supports Markdown out-of-the-box along with the alternative authoring formats proposed for Lightweight DITA.
For more information on publishing with Markdown/DITA workflows, see DITA-OT³ Markdown Support.
]]>The title was clearly a bit provocative, as many people do find tweaking default output tricky — but my point was that this has gotten easier and depending on what you need to change, you may find it’s not nearly as hard as you recall.
Most of the talk was about the sorts of things you can change via dita
command arguments and options, DITA-OT parameter settings, and configuration properties, such as:
The presentation continued with a few examples of simple plug-in–based customizations, and links to new topics in the DITA-OT documentation, including:
The highlight of the presentation was the announcement of my new “DITA Bootstrap” plug-in for DITA-OT 3.2, which generates HTML5 output with a basic Bootstrap template that includes responsive grid layout, global navigation menu and a table-of-contents sidebar.
The global navigation bar at the top is implemented as a custom header file that can be inverted or overridden via the standard DITA-OT args.hdr
parameter setting, and custom CSS.
And thanks to the new plug-in registry at dita-ot.org/plugins, you can now install DITA Bootstrap and other plug-ins just by passing their name to the dita
command in DITA-OT 3.2:
dita --install net.infotexture.dita-bootstrap
So if you’ve struggled to customize the toolkit’s output in the past, you may want to give it another try.
As the number of custom plug-ins in the new registry increases, you may find something there that’s close to what you need, or at least a solid basis for your own customizations.
The more of us that share our plug-in code and publish to the registry, the easier it will be for others to build something new.
The registry provides a searchable list of plug-ins at dita-ot.org/plugins.
You can now install plug-ins by name via the dita
command, without having to download them first:
dita --install net.infotexture.dita-bootstrap
The dita
command will connect to the registry and look for a compatible plug-in version, download and install it to your local toolkit installation.
The registry is a Git repository at github.com/dita-ot/registry. New plug-ins or new versions can be added to the registry by sending a pull request that includes a new plug-in entry in JSON format.
For more information, see “Adding plug-ins via the registry” in the DITA-OT docs.
]]>One of the most popular posts on this site is Marking Down DITA, my 2015 article on the rise of Markdown as an alternative input method for DITA projects. The sustained interest is at least partly due to its citation in the first Lightweight DITA committee note on the upcoming standard.
That post provided background information for people who are new to the concept of lightweight markup languages and how they relate to more structured authoring formats like DITA.
— But that was years ago, and a lot has happened since then…
At this year’s DITA Europe conference in Berlin, I gave a follow-up talk that explained how DITA Open Toolkit 3.0 supports Markdown right out of the box along with the alternative authoring formats proposed for Lightweight DITA.
This article provides a summary of that presentation and highlights recent changes in the toolkit’s Markdown support.
The level of Markdown support that DITA Open Toolkit provides depends on the version of the toolkit that you are using.
Since I wrote Marking Down DITA, several versions of the DITA-OT Markdown plug-in were released to improve Markdown parsing, resolve issues and support additional features, including:
markdown_github
transtype generates GitHub-flavored Markdown (GFM), which can be used to publish DITA content to GitHub wikis, or other publishing environments that support GFM.<dita>
composite topic.mailto:
URI scheme.md
extension can now be used in @format
attribute values to trigger Markdown processing.If you’re still running DITA-OT 2.2 – 2.5, you can install the plug-in as described in my earlier post:
dita --install https://github.com/jelovirt/dita-ot-markdown/releases/download/1.3.0/com.elovirta.dita.markdown_1.3.0.zip
The Markdown support that was previously provided by the external dita-ot-markdown
plug-in has been extended and bundled with the default toolkit installation for DITA-OT 3.0.
This means you can now use Markdown topics in DITA publications (or convert DITA source files to Markdown) right out of the box without having to install any additional plug-ins first.
The new Lightweight DITA plug-in replaces the earlier Markdown plug-in and builds on its capabilities to provide additional support for Lightweight DITA (LwDITA).
DITA Open Toolkit 3.0 provides preview support for the MDITA and HDITA authoring formats planned for LwDITA.
These new formats have been proposed1 as alternative representations of DITA content in Markdown or HTML.
MDITA is the LwDITA authoring format based on Markdown. It is designed for users who want to write structured content with the minimum of overhead, but who also want to take advantage of the reuse mechanisms associated with the DITA standard and the multi-channel publishing afforded by standard DITA tooling.
Recent proposals include two profiles for MDITA:
The Markdown DITA parser included in the org.lwdita
plug-in provides preliminary support for LwDITA profiles — and additional Markdown constructs.
To apply LwDITA-specific processing to Markdown topics, set the @format
attribute on a topic reference to mdita
:
<map>
<topicref href="mdita-topic.md" format="mdita"/>
</map>
In this case, the first paragraph in the topic will be treated as a short description, for example, and additional metadata can be specified for the topic via a YAML front matter block.
Note: MDITA parsing is stricter than the more lenient document parsing approach that is applied to Markdown documents when the @format
attribute is set to markdown
.
HDITA is the LwDITA authoring format based on HTML5 to support structured content authoring with tools designed for HTML authoring.
The HDITA parser included in the org.lwdita
plug-in provides preliminary support for these constructs.
To apply LwDITA-specific processing to HTML topics, set the @format
attribute to hdita
:
<map>
<topicref href="hdita-topic.html" format="hdita"/>
</map>
So while the Lightweight DITA standard is still evolving, the basic principles are already clear — and DITA-OT³ now offers the processing tools you need to use Markdown in your DITA publishing workflows.
The toolkit’s support for Lightweight DITA will mature further as the emerging standard solidifies, but there’s no need to purchase proprietary software to make it easier for authors to contribute to DITA publications, facilitate review processes with less technical audiences, or feed DITA content into Markdown-based publishing systems.
DITA-OT³ enables a broad range of new use cases, and we can look forward to hearing more about what people are doing with these new capabilities in upcoming conference presentations and future articles — here and elsewhere.
Stay tuned…
See the Lightweight DITA Committee Note № 1 ↩
The discussion will cover the design and evolution of the plugins, show how they’re used and configured and how you can integrate the plugins in your own workflows.
Join us to talk shop and meet other DITA users in the area.
— Hope to see you there!
]]>The course begins by exploring how the principles of placemaking and wayfinding from the physical world apply to digital information systems. As an introduction to the practice of information architecture, the course covers the fundamental concepts of structural design that provide the foundation for shared information environments, including organization schemes, labeling, navigation, and search systems.
Students learn to evaluate existing information systems in practical exercises with public content, applying their knowledge to visualize structure and recommend improvements to support usability, findability, and understanding.
In this semester’s exercises, IA students drafted sitemaps for museum organizations, indexed technical documentation for the DITA Open Toolkit, proposed navigation refinements for the Universalmuseum Joanneum and analyzed the information architecture of eBay’s German seller center portal.
I’ve been impressed with many of my students’ recommendations in these exercises and I’m confident that some of their suggestions may be incorporated into future iterations of the information systems they analyzed.
These practical applications and the interdisciplinary approach distinguish the Master’s program in Content Strategy at the University of Applied Sciences by providing students with direct access to content industry experts and a broad range of project partners.
The program is now in its third year, and this semester there’s been a strong focus on connecting the content of the courses in Content Auditing, Information Architecture, and User Research and Interaction Design.
In a recent blog post on the university website, Lisa M. Moore describes how our common project came about and how the related disciplines that comprise an enterprise content strategy can work together to craft a coherent experience.
I am very grateful to Lisa for bringing me into the program, and it’s been a pleasure working with her and Christopher Lee Ball, Head of User Experience at Digitas LBi to bring these courses together.
We’ll be wrapping up our portion of the program next week in London, where students will meet with content teams at Facebook and the UK’s Government Digital Services, and test their prototypes at DLBi’s in-house user testing facilities.
If you’re interested in earning a degree in Content Strategy, the university is now accepting applications for the 2017 program.
]]>
By exploring how the DITA-OT docs are built, participants will see examples of recent DITA features in action, learn more about how the toolkit works, what they need to know to contribute to the project, and consider techniques that may be applicable to their own publishing projects.
Join us to learn how the DITA-OT project uses open-source tools and modern development techniques to publish the docs, including:
The slides are available on Speaker Deck, and embedded here for convenience:
]]>This all-day event featured presentations on API design and documentation solutions like API Blueprint, the RESTful API Modeling Language (RAML), and the Open API Initiative (formerly known as Swagger). The day began with a look at the needs of API documentation users and how API docs differ from other forms of technical communication. The afternoon continued with a series of lightning talks and case studies on various approaches to documenting APIs.
In my talk I proposed a hybrid approach to API documentation that combines Markdown output generated by API docs tools with more complex content authored in DITA and published via the DITA-OT Markdown plug-in for delivery via GitBook or other Markdown-based publishing systems.
The slides are available on Speaker Deck, and embedded below for convenience.
Judging by the level of interest and lively discussions, I think we can look forward to more opportunities to bring technical communication experts and developers together, and build on the knowledge and tools we have to produce better API docs.
]]>