https://github.com/jason-fox/fox.jason.readthedocs
DITA-OT Plug-in which creates a set of output files suitable for a ReadTheDocs documentation project.
https://github.com/jason-fox/fox.jason.readthedocs
dita dita-ot dita-ot-plugin readthdocs
Last synced: about 1 year ago
JSON representation
DITA-OT Plug-in which creates a set of output files suitable for a ReadTheDocs documentation project.
- Host: GitHub
- URL: https://github.com/jason-fox/fox.jason.readthedocs
- Owner: jason-fox
- License: apache-2.0
- Created: 2019-03-24T20:40:36.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-02-17T15:28:08.000Z (over 2 years ago)
- Last Synced: 2025-02-04T13:27:36.902Z (over 1 year ago)
- Topics: dita, dita-ot, dita-ot-plugin, readthdocs
- Language: Java
- Homepage: https://jason-fox.github.io/dita-ot-plugins/readthedocs
- Size: 326 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ReadTheDocs Plugin for DITA-OT [
](https://readthedocsdita-ot.rtfd.io/)
[](http://www.apache.org/licenses/LICENSE-2.0)
[](http://www.dita-ot.org/4.0)
[](https://github.com/jason-fox/fox.jason.readthedocs/actions?query=workflow%3ACI)
[](https://coveralls.io/github/jason-fox/fox.jason.readthedocs?branch=master)
[](https://sonarcloud.io/dashboard?id=fox.jason.readthedocs)
This is a [DITA-OT Plug-in](https://www.dita-ot.org/plugins) which creates a set of output files suitable to create a
[ReadTheDocs](https://readthedocs.org) 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
```yaml
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
```
:arrow_forward: [Video from DITA-OT Day 2019](https://youtu.be/vobY_ha5nd0)
[](https://youtu.be/vobY_ha5nd0)
Table of Contents
- [Install](#install)
- [Installing DITA-OT](#installing-dita-ot)
- [Installing the Plug-in](#installing-the-plug-in)
- [Usage](#usage)
- [Creating a ReadtheDocs Project out of existing DITA content](#creating-a-readthedocs-project-out-of-existing-dita-content)
- [Coverting a ReadtheDocs Project into DITA content](#coverting-a-readthedocs-into-dita)
- [Parameter Reference](#parameter-reference)
- [Contribute](#contribute)
- [License](#license)
## Install
The ReadTheDocs Plug-in for DITA-OT has been tested against [DITA-OT 4.x](http://www.dita-ot.org/download). 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](https://www.dita-ot.org/4.0/topics/installing-client.html).
1. Download the `dita-ot-4.0.zip` package from the project website at
[dita-ot.org/download](https://www.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.
```console
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:
```console
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:
```console
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:
```console
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](LICENSE) © 2019 - 2022 Jason Fox