Static HTML and PDF generator tool for generating documentation from Markdown files.
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
- the online.twig
and pdf.twig
templates to use for rendering HTML/PDF respectively/docs-src/features
- if you have features, this should contain your featuresAdditionally, 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="<auth token>" \
--rm ghcr.io/roave/docbooktool:latest --html --pdf --confluence
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 [] []
$
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 page 1234
will 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.feature
as a code blockpuml
syntax will be converted into a PlantUML diagram. Note your diagram
must start and end with @startuml
and @enduml
respectively.{{src-json:test.json}}
will render $(DOCBOOK_TOOL_CONTENT_PATH)/test.json
as a code block. Only json
is
supported at the moment.Example showing all syntax can be seen in test/fixture/docbook/test.md
.
DOCBOOK_TOOL_CONTENT_PATH
- the path where your Markdown documentation is kept (Required)
/path/to/myproject/docs/book
DOCBOOK_TOOL_TEMPLATE_PATH
- the path to your Twig templates called online.twig
and pdf.twig
(Required)
/path/to/myproject/docs/template
DOCBOOK_TOOL_FEATURES_PATH
- the base path from where features are stored (Optional)
/path/to/myproject/features
DOCBOOK_TOOL_OUTPUT_HTML_FILE
- where to generate the HTML documentation (Required, if using --html
)
/path/to/myproject/build/docs/index.html
DOCBOOK_TOOL_OUTPUT_PDF_PATH
- where to generate the PDF files, if used (Required, if using --pdf
)
/path/to/myproject/build/docs/pdf
DOCBOOK_TOOL_CONFLUENCE_URL
- the base URL of confluence (/rest/api/content
is appended to this, so don't
include that) (Required, if using --confluence
)
https://confluence.mycompany.com
DOCBOOK_TOOL_CONFLUENCE_AUTH_TOKEN
- the Authorization
header value to use (Required, if using --confluence
in
a non-interactive terminal).
Bearer MTA4NjU3Njg2OTEyOt53L29niGxOkuIZJpKcgjItNMoI
Basic bXktdXNlcm5hbWU6bXktcGFzc3dvcmQ=
DOCBOOK_TOOL_CONFLUENCE_SKIP_CONTENT_HASH_CHECKS
- Should the content hash check be skipped. Set to yes
to skip
the hash check. Note that this means every time the tool runs, the content will create a version in Confluence, even
if nothing has changed. This is a workaround for some API issues with certain Confluence setups, so we don't
recommend enabling this unless you have a specific need to.
no