Authored documentation pages are referred to as guides. Guides should be authored in GitHub Flavoured Markdown (GFM) since using HTML will make them dependant on the theme in use at the time they were written, and therefore resistant to change. The flexible approach is to use GitHub Flavoured Markdown.
Guides written using GitHub Flavoured Markdown
have a file extension of
.md, those written in HTML are referred to as 'templates' and have a file extension of
Guides can be applied at two levels:
Global guides are located within directory
and per-specification guides are located within directory
If you tell DapperDox where to find your local assets, then on startup, it will locate and build
pages for all of your guides, maintaining the directory structure it finds below the
The DapperDox assets example
examples/guides/assets/ contains three guides:
The first two are global documents, available outside any specification reference page. The third is a guide specific to the Petstore specification.
To build and make these guides available, pass DapperDox the configuration parameters:
-assets-dir=<DapperDox-source-directory>/examples/guides/assets \ -spec-dir=<DapperDox-source-directory>/examples/specifications/petstore \ -force-specification-list=true
will build these three guides, making them available a
When presenting a single specification, DapperDox will set its homepage to that specification's summary page and not the specification list page, which lists all available specifications. Since the
markdown2guides are global, they will only be listed in the side navigation of the specification list page, and thus will not be visible. The
-force-specification-list=trueoption instructs DapperDox to show the specification list page.
When viewing the specification list page, the navigation rendered at the side of the page will show two entries:
▾ Level2 markdown2 markdown
and when viewing the Swagger Petstore specification reference documentation, the side navigation shows the Petstore help guide:
PetstoreHelp ▸ Everything about your Pets ▸ Access to Petstore orders ▸ Operations about user
The entries listed below
PetstoreHelp are automatically generated by DapperDox from the Petstore specification.
By default, the side navigation will reproduce the directory structure beneath the
However there is an enforced limit of two levels in the navigation, which consequently restricts the depth of
your directory structure.
If you need a deeper directory structure, or have a file naming convention that does not lend itself to navigation titles, you can take control of the side navigation through metadata.
DapperDox allows the integration of guides to be controlled with some simple metadata. This metadata is added to the
beginning of GFM files as a block of lines containing
key: value pairs. DapperDox will stop processing
any metadata present at the first blank line, and consider the rest of the file as content.
This metadata allows you to control the side navigation hierarchy, grouping and page naming.
The example assets
examples/metadata/assets demonstrate the use of metadata to control guide navigation. To run
these examples, pass the following assets configuration to DapperDox:
Three example global guides are provided, each demonstrating a different directory structure:
When DapperDox renders the documentation, it uses the embedded metadata to name, sort and structure the
navigation entries. If loading a single specification, remember to pass the
option to enable the specification list summary home page, from where you will be able to see the global
The first example file
examples/metadata/assets/templates/guides/markdown.md contains metadata as follows:
Navigation: Examples/A markdown example SortOrder: 310 Note: This top section is just MetaData and gets stripped to the first blank line. # This page was written using Git Flavoured Markdown - With metadata ...
The third example file
examples/metadata/assets/templates/guides/level2/level3/markdown2.md, which is three
directory levels deep and thus would normally give an error, renders correctly because of it's
Navigation: Overview/Another example SortOrder: 210
Navigation: entry forces a page side navigation entry that is just two levels deep. The side
navigation for these three example guides is therefore:
Getting Started ▾ Overview Another example ▾ Examples A markdown example
By using metadata, the side navigation wording and structure is divorced from the underlying file naming convention, structure and depth.