ReadTheDocs Plug-in

This is a DITA-OT Plug-in which creates a set of output files suitable to create a ReadTheDocs documentation project. The transform is an extension of the existing DITA-OT markdown plug-in (org.lwdita) and creates a well-formatted mkdocs.yaml file.

Examples

site_name: 'ReadTheDocs Plug-in'

    pages:
      -  Home: index.md
      -  'ReadTheDocs':
           -  'Examples': 'topics/examples.md'
           -  'Full list of features': 'topics/features-full.md'
           -  'Basic usage': 'topics/basic-usage.md'
    theme: mkdocs
Figure 1. Sample MkDocs.yaml File

Additionally it is possible to use the plug-in to create a DITA <bookmap> file from an existing mkdocs.yaml file. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap>
    <title>ReadTheDocs Plug-in</title>
    <frontmatter>
        <bookabstract format="md" href="index.md"/>
        <booklists>
            <toc/>
        </booklists>
    </frontmatter>
    <chapter>
        <topicmeta>
            <navtitle>ReadTheDocs</navtitle>
        </topicmeta>
        <topicref format="md" href="topics/examples.md"/>
        <topicref format="md" href="topics/features-full.md"/>
        <topicref format="md" href="topics/basic-usage.md"/>
    </chapter>
</bookmap>
Figure 2. Sample Ditamap

Limitations

It is assumed that the underlying markdown is well-formed and usable by DITA-OT - in other words every heading must be at most one level deeper that the previous heading. To ensure this, it is recommended to prettify the existing markdown using prettier and fix the markup levels using the DITA Validatorfix-dita transform.

In general, the structure of a ReadTheDocs project is more limited than a typical *.ditamap, for example, an index.md summary file is should be found root of the project - this is the equivalent of a <bookabstract>. For the readthedocs transform, the opening topic of the ditamap will be used as the index.md if no <bookabstract> is found. Also <chapter> divisions should be given a <navtitle> only and no @href if they are to be recognized as such in the ReadTheDocs navigation sidebar.

Install

This plug-in extends the standard org.lwdita plug-in which should be present in the base installation. It has no further external dependencies, and can be installed from the command line.

Run the plug-in installation commands: 

dita install https://github.com/jason-fox/fox.jason.readthedocs/archive/master.zip

The dita command line tool requires no additional configuration.

Usage

Like any other transform, when invoked directly, the readthedocs transform requires an input document.

Creating a ReadtheDocs Project from DITA content

To create the files for a ReadtheDocs project, use the readthedocs transform and set the --input parameter to point to a *.ditamap file: 

dita --format readthedocs \
    --input document.ditamap

Converting a ReadtheDocs Project into DITA content

To create the files for a DITA-OT project, use the mkdocs2dita transform and set the --input parameter to point to an mkdocs.yml file: 

dita --format mkdocs2dita \
    --input mkdocs.yml

Parameter Reference

  • args.css - Specifies the name of a custom .css file. The css is added to the mkdocs.yml file as extra_css
  • args.csspath - Specifies the location of a copied .css file relative to the output directory.
  • args.cssroot - Specifies the directory that contains the custom .css file.
  • args.readthedocs.theme - Specifies a theme to style the ReadTheDocs output (default: readthedocs)
  • args.readthedocs.template - Specifies a template mkdocs.yml file to use - the template can hold additional readthedocs attributes which are not generated by the transform.
  • args.readthedocs.use.pages - Specifies whether to use pages rather than nav (default no)