___              _ _ ____
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/

[ Home | What is AsciiDoxy? | Getting started | Reference documentation | Examples | Contributing | Changelog | GitHub ]

Custom templates

This feature is experimental. The API used by the templates is currently not stable and may change without warning in any update of AsciiDoxy.

AsciiDoxy comes with builtin templates to generate API reference for the programming languages it supports. It is possible to provide your own set of templates to customize or extend the output generated by AsciiDoxy.

1. Custom template directory

Custom templates need to be provided to AsciiDoxy using the --template-dir command line argument. The argument must point to an existing directory with a predefined structure.

asciidoxy --template-dir src/templates my-document.adoc

Templates are stored in a subdirectory for the language they apply to. The filename is the name of the kind of element with the extension .mako.

For example a template directory where the class template for c++ and java are overridden should look like this:

templates
├── cpp
│   └── class.mako
└── java
    └── class.mako

2. Replacing builtin templates

The custom template directory can be used to replace the builtin templates. When a template directory is provided, AsciiDoxy will always first check whether a custom version of the template is present. If it its, it will prefer the custom version, otherwise it will fall back to the builtin templates.

The builtin templates can be found in the source code of AsciiDoxy in asciidoxy/generator/templates. You can copy the templates to customize into your custom templates directory as a starting point.

3. Using custom templates for specific cases

Alternatively, custom templates can be used explicitly in insert commands. Then the custom template is only used for that specific insert command. To use this, make sure the custom template has a name that is not used yet for a builtin template:

templates
└── java
    └── mycustomclass.mako

In your AsciiDoc documents you can explicitly use the template by providing the template argument to the insert command:

${insert("MyNamespace::MyClass", template="mycustomclass")}
AsciiDoxy