jason-fox/fox.jason.readthedocs

DITA-OT Plug-in which creates a set of output files suitable for a ReadTheDocs documentation project.

ReadTheDocs Plugin for DITA-OT

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

Sample mkdocs.yaml File

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

▶️ Video from DITA-OT Day 2019

Table of Contents

• Install
  • Installing DITA-OT
  • Installing the Plug-in
• Usage
  • Creating a ReadtheDocs Project out of existing DITA content
  • Coverting a ReadtheDocs Project into DITA content
  • Parameter Reference
• Contribute
• License

Install

The ReadTheDocs Plug-in for DITA-OT has been tested against DITA-OT 4.x. It is recommended that you upgrade to the latest version.

Installing DITA-OT

The ReadTheDocs Plug-in for DITA-OT is a plug-in for the DITA Open Toolkit.

• Full installation instructions for downloading DITA-OT can be found here.

  1. Download the dita-ot-4.0.zip package from the project website at dita-ot.org/download
  2. Extract the contents of the package to the directory where you want to install DITA-OT.
  3. Optional: Add the absolute path for the bin directory to the PATH system variable. This defines the necessary environment variable to run the dita command from the command line.

curl -LO https://github.com/dita-ot/dita-ot/releases/download/4.0/dita-ot-4.0.zip
unzip -q dita-ot-4.0.zip
rm dita-ot-4.0.zip

Installing the Plug-in

• Run the plug-in installation command:

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 transforms require an input document

Creating a ReadtheDocs Project out of existing DITA content

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

PATH_TO_DITA_OT/bin/dita -f readthedocs -i document.ditamap

Coverting 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 a mkdocs.yml file:

PATH_TO_DITA_OT/bin/dita -f mkdocs2dita -i 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)

Contribute

PRs accepted.

License

Apache 2.0 © 2019 - 2022 Jason Fox

fox.jason.readthedocs's Issues

Folder with media objects is not copied into the docs folder

Starting point

I have the following in my project:

• Folder with DITA topics
• subfolder with media objects (images) at the same level as topics.

Plug-in behaviour

The last part of the DITA-OT transformation moves the Markdown files into the docs folder, but the folder with media objects is not moved which causes broken links. You have to manually move the folder with media objects in the docs folder.

Expected behaviour

the folder with media objects is also moved to the docs folder.

Background information

• DITA-OT: 3.6.1
• version DITA-OT plug-in: 1.4.1

Reference files

Attached files for reference: _example_media.zip

java.lang.IndexOutOfBoundsException when using mkdocs2dita

I'm trying to use the plugin to convert yml files to ditamaps + dita. I was able to validate that the commands I'm running work when I use the sample yml file /test/create-ditamap/mkdocs.yml, but they throw java.lang.IndexOutOfBoundsException for all of the 'real' yml files I'm testing. I've attached one. Note that I tried omitting the 'markdown_extensions' and 'plugins' blocks from the yml, but I still get the same error. These yml files work fine for markdown conversions.

Sample output:
[copy] sbc_cne_troubleshooting omitted as C:\workgit\dt-toolsinstructions\out\sbc_cne_troubleshooting is up to date.
[copy] sbc_cne_troubleshooting\images omitted as C:\workgit\dt-toolsinstructions\out\sbc_cne_troubleshooting\images is up to date.
[copy] sbc_cne_troubleshooting\img omitted as C:\workgit\dt-toolsinstructions\out\sbc_cne_troubleshooting\img is up to date.
[copy] sbc_cne_upgrade omitted as C:\workgit\dt-toolsinstructions\out\sbc_cne_upgrade is up to date.
[copy] sbc_cne_upgrade\img omitted as C:\workgit\dt-toolsinstructions\out\sbc_cne_upgrade\img is up to date.
[antcall] Exiting C:\workgit\dt-toolsinstructions\target\dita\build.xml.
Error: java.lang.

IndexOutOfBoundsException: Index: 0, Size: 0

args.readthedocs.template parameter does not use the selected template

Starting point

When I point the parameter args.readthedocs.template to a YML file, this YML file is not used to create the final mkdocs.yml in my transformation output. The default one is used.

Expected behavior

The plug-in uses the YML file I indicated.

Background information

• DITA-OT: 3.6.1
• Plug-in version: 1.4.1
• Published with OxygenXML 24.0

Reference file

mkdocs.zip

Pages configuration is deprecated

I get the following information in my command prompt when using the default YML file.

WARNING  -  Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in
            a future release of MkDocs. Use 'nav' instead.

Could you update pages: to nav: in the YML file?

Background information

• DITA-OT 3.6.1
• Plug-in version 1.4.1