Creating authored documentation pages

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 .tmpl.

Global and per-specification guides

Guides can be applied at two levels:

  1. Per-specification guides, which are available when browsing specification reference documentation.
  2. Global guides, which are available when a user is not browsing specification reference documentation.

Global guides are located within directory {local_assets}/templates/guides/, and per-specification guides are located within directory {local_assets}/sections/{specification_ID}/templates/guides/.

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 /guides/ directory

Example

The DapperDox assets example examples/guides/assets/ contains three guides:

  1. templates/guides/markdown.md
  2. templates/guides/level2/markdown2.md
  3. sections/swagger-petstore/templates/guides/PetstoreHelp.md

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 http://localhost:3123/.

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 markdown and markdown2 guides 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=true option 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 guides/ directory, 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.

Controlling guide behaviour with 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.

Example

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:

-assets-dir=<DapperDox-source-directory>/examples/guides/assets

Three example global guides are provided, each demonstrating a different directory structure:

  1. examples/metadata/assets/templates/guides/markdown.md
  2. examples/metadata/assets/templates/guides/level2/markdown2.md
  3. examples/metadata/assets/templates/guides/level2/level3/markdown2.md

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 -force-specification-list=true option to enable the specification list summary home page, from where you will be able to see the global documentation.

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 metadata.

Navigation: Overview/Another example
SortOrder: 210

The 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.

The ordering of pages within the page side navigation is controlled by the addition of SortOrder metadata. Refer to the metadata section for further details.