Docmatic is a JVM based toolkit for generating documentation. It accepts as input any combination of Markdown, DocBook or HTML, and generates HTML or PDF output.
- Existing tool-chains for the JVM are unwieldy, slow and hard to customise. Docmatic is small, fast and easy to install.
- Docbook has a comprehensive model for documentation, but is awkward to use for authoring documents. Markdown, on the other hand, is nice for authoring, but the resulting documents lack a lot of useful structural information. Docmatic is an experiment in allowing you to build documentation from these two formats, using the strengths of each as appropriate.
- Generate single or multi-paged HTML.
- Themes.
- Java API, to allow you to programmatically build, transform, theme, or render a document.
Docmatic can parse a subset of Markdown, HTML 4.01 and 5, and DocBook 4.5 and 5. You can also use the API to build a document programmatically.
Note that Docmatic is a very early work-in-progress, so not much of these input formats is supported yet.
Supported syntax:
- Paragraphs
- Setext style headers
- Unordered and ordered lists - paragraphs only (no nested lists, headers, etc).
`code`_emphasis_
Supported DocBook 5 elements:
<book>, with<title>,<part>,<chapter>,<appendix>child elements only.<part>, with<title>,<chapter>,<appendix>child elements only.<chapter>, with<title>,<section>,<para>,<itemizedlist>,<orderedlist>,<example>,<programlisting>child elements only.<appendix>, with<title>,<section>,<para>,<itemizedlist>,<orderedlist>,<example>,<programlisting>child elements only.<section>, with<title>,<section>,<para>,<itemizedlist>,<orderedlist>,<example>,<programlisting>child elements only.<para>, with text and<classname>,<code>,<literal>,<emphasis>,<xref>,<link>child elements only.<title>, with text and<classname>,<code>,<literal>,<emphasis>,<xref>,<link>child elements only.<itemizedlist>, with<listitem>child elements only.<orderedlist>, with<listitem>child elements only.<listitem>, with<para>,<itemizedlist>,<orderedlist>,<example>,<programlisting>child elements only.<example>, with<title>,<para>,<itemizedlist>,<orderedlist>,<programlisting>child elements only.<programlisting>, with text only.<classname>, with text and<classname>,<code>,<literal>,<emphasis>child elements only.<code>, with text and<classname>,<code>,<literal>,<emphasis>child elements only.<literal>, with text and<classname>,<code>,<literal>,<emphasis>child elements only.<emphasis>, with text and<classname>,<code>,<literal>,<emphasis>child elements only.<link>, with text and<classname>,<code>,<literal>,<emphasis>child elements only.<xref>
Supported DocBook 4.5 elements:
<book>, with<bookinfo>child element.<bookinfo>, with<title>child element only.<ulink>, with text and<classname>,<code>,<literal>,<emphasis>child elements only.
You can mix DocBook 5 and DocBook 4.5 elements in the same document.
Supported HTML elements:
<html>, with<body>,<p>child elements only. Also allows text.<body>, with<p>child elements only. Also allows text.<p>elements with, text only.
The HTML parser is fairly lenient. You can leave out the doctype declaration, <html> and <body> elements. Any text
outside a block element is wrapped in an implicit <p> element.
Can generate HTML 4 and PDF output. There are some built-in themes that offer some degree of customisation. You can also customise via the API, by implementing your own output renderer or theme.
Run ./gradlew installApp to build an installation in build/install/docmatic.
docmatic <output-formats> <themes> --out <output-dir> <input-files>*
-
--pdfGenerates PDF.
-
--htmlGenerates HTML 4.
-
--minimalGenerates minimal styling and markup.
-
--defaultSome lightweight styling.
-
--fixed-widthFixed page width (HTML only).
Docmatic guesses the type of each input file based on its extension:
.xmlis treated as a DocBook file..htmlis treated as an HTML file.- Everything else is treated as a Markdown file.
Use a Parser implementation to build a Document. Use one or more Renderer implementations to generate output
from that Document. Use a Theme implementation to tweak the output.
Docmatic is licensed under the ASL 2.0.
- Docbook
<xref/>elements can refer to<book>,<part>,<chapter>,<appendix>and<section>elements only. - Cannot parse an HTML 4 doctype declaration.
- Inlines nested in PDF links are separately clickable.