Roave Docbook Tool
Static HTML and PDF generator tool for generating documentation from Markdown files.
- Generates a deployable HTML file from Markdown documentation
- Generates PDF files of the same documentation that can be deployed alongside
- Link pages to a Confluence instance so the content can be mirrored there
Running with Docker
A Docker image is provided with all the pre-built tools. You will need to map several volumes into the container:
/docs-package- this will be where the tool writes the output/docs-src/book- the path containing the Markdown files to be rendered/docs-src/templates- theonline.twigandpdf.twigtemplates to use for rendering HTML/PDF respectively/docs-src/features- if you have features, this should contain your features
Additionally, you can provide environment variables to override the default paths used, or to enable the Confluence functionality.
# Will build the test fixtures and put in a folder called "build"
docker run \
-v $(pwd)/test/fixture/docbook:/docs-src/book \
-v $(pwd)/test/fixture/templates:/docs-src/templates \
-v $(pwd)/test/fixture/feature:/docs-src/features \
-v $(pwd)/build:/docs-package \
--rm ghcr.io/roave/docbooktool:latest
# Will build your stuff - replace host paths as appropriate
docker run \
-v $(pwd)/docs/book:/docs-src/book \
-v $(pwd)/docs/templates:/docs-src/templates \
-v $(pwd)/features:/docs-src/features \
-v $(pwd)/build:/docs-package \
--rm ghcr.io/roave/docbooktool:latest
# Will generate HTML, PDF, and update any configured Confluence pages
docker run \
-v $(pwd)/docs/book:/docs-src/book \
-v $(pwd)/docs/templates:/docs-src/templates \
-v $(pwd)/features:/docs-src/features \
-v $(pwd)/build:/docs-package \
-e DOCBOOK_TOOL_CONFLUENCE_URL=https://confluence.mycompany.com \
-e DOCBOOK_TOOL_CONFLUENCE_AUTH_TOKEN="Basic bXktdXNlcm5hbWU6bXktcGFzc3dvcmQ=" \
--rm ghcr.io/roave/docbooktool:latest --html --pdf --confluence
Usage
bin/docbook-tool [--html] [--pdf] [--confluence]
For example, this command would generate only the HTML documentation:
$ DOCBOOK_TOOL_CONTENT_PATH=/path/to/myproject/docs/book \
> DOCBOOK_TOOL_TEMPLATE_PATH=/path/to/myproject/docs/template \
> DOCBOOK_TOOL_OUTPUT_HTML_FILE=/path/to/myproject/build/docs.html \
> bin/docbook-tool --html
[2021-01-28T12:28:41.000628+00:00] cli.INFO: Writing HTML output to /path/to/myproject/build/docs.html [] []
$
Formatting
We have limited support for YAML front matter:
title: Your title here- when specified, this will be used as the page title ({{ title }}in template)pdf: true- when specified, a PDF will be generated for thisconfluencePageId: 1234- when specified, Confluence page1234will be updated (numeric ID only)order: 100- when specified, pages are ordered by this. Defaults to 100. Matching values are sorted alphabetically.
Additionally, we have a special Markdown syntax:
{{feature:test.feature}}will render$(DOCBOOK_TOOL_FEATURES_PATH)/test.featureas a code block- Code blocks (triple-backtick) with the
pumlsyntax will be converted into a PlantUML diagram. Note your diagram must start and end with@startumland@endumlrespectively.
Example showing all syntax can be seen in test/fixture/docbook/test.md.
Environment variables
DOCBOOK_TOOL_CONTENT_PATH- the path where your Markdown documentation is kept (Required)- Example:
/path/to/myproject/docs/book
- Example:
DOCBOOK_TOOL_TEMPLATE_PATH- the path to your Twig templates calledonline.twigandpdf.twig(Required)- Example:
/path/to/myproject/docs/template
- Example:
DOCBOOK_TOOL_FEATURES_PATH- the base path from where features are stored (Optional)- Example:
/path/to/myproject/features
- Example:
DOCBOOK_TOOL_OUTPUT_HTML_FILE- where to generate the HTML documentation (Required, if using--html)- Example:
/path/to/myproject/build/docs/index.html
- Example:
DOCBOOK_TOOL_OUTPUT_PDF_PATH- where to generate the PDF files, if used (Required, if using--pdf)- Example:
/path/to/myproject/build/docs/pdf
- Example:
DOCBOOK_TOOL_CONFLUENCE_URL- the base URL of confluence (/rest/api/contentis appended to this, so don't include that) (Required, if using--confluence)- Example:
https://confluence.mycompany.com
- Example:
DOCBOOK_TOOL_CONFLUENCE_AUTH_TOKEN- theAuthorizationheader value to use (Required, if using--confluencein a non-interactive terminal)- Example:
Basic bXktdXNlcm5hbWU6bXktcGFzc3dvcmQ=
- Example:
14 Sep 25, 2022
7 Feb 21, 2022
5 Dec 9, 2022
104 Nov 12, 2022
14.3k Dec 28, 2022
2.4k Dec 29, 2022
230 Jan 7, 2023
6 Sep 29, 2022
3 Jul 1, 2022
76 Dec 30, 2022
1 Dec 26, 2021
3 Apr 26, 2022
329 Dec 14, 2022
173 Dec 30, 2022
16 Dec 24, 2022
15 Nov 8, 2022
1 Oct 4, 2022
4.6k Dec 16, 2022
719 Jan 1, 2023