Publishing from Markdown

To publish the markdown documentation into other formats you can use the publish command:

apidocs.exe publish --output C:\html-output --template .\html-template --format mustache

Parameters

Option	Description
--output <path>	Required. Output directory for documentation.
--format <format>	Specify the format for the output documentation.
--template <value>	Specify the path to a folder that contains output template content.
--template-filename <value>	Specify the name of the file in the template folder that should be used for the output template.
--file-ext <.htm>	Specify the extension used for files generated from markdown input.
--allow-unsafe-html	When converting to HTML, allow HTML tags in the markdown to be passed through without being encoded.

Publishing Basic HTML

APIDocs has two different HTML output formats. The first format HTML provides basic HTML document output that can be customized through CSS or editing the HTML directly. This format has no options, but can be used as follows:

apidocs.exe publish --format html --output C:\html-output

This method fixes up relative links within the documentation to point to the properly named HTML output file.

Publishing HTML with Templates

APIDocs can also use a Mustache formatted HTML template to generate HTML output for your website. Using this format you provide a template directory which contains a Mustache template and any other content that should be published to the output folder (stylesheets, images, scripts, etc).

APIDocs will read the template and use it to generate an output HTML document per input markdown file. Output files are written into the same place in the folder hierarchy that the input file was located.

This method fixes up relative links within the documentation to point to the properly named HTML output file.

Available Template Objects

Inside the Mustache template the following properties are made available to be inserted into the output document:

Name	Value	Description
Page	Page Annotation	Properties from the Page Annotation comment block.
Body	HTML Text	The HTML text converted from the Markdown input.
Headers	Collection(TocItems)	A collection of information about the table of contents for the document set.
HtmlHeaderAdditions	Collection(string)	A collection of tags that should be added to the tag.
HtmlFooterAdditions	Collection(string)	A collection of tags that should be written to the footer of the HTML page.

Page Annotation

Name	Value	Description
Title	String	The title of the page
Description	String	The description provided for the page
Keywords	String	A string list of keywords for the page
CanonicalUrl	String	The specific canonical URL for the content on the page
Section	String	A specifier for the section of the website the page lives in
TocPath	String	A slash-separated table of contents hierarhcy for the page
HeaderAdditions	Collection(string)	A list of tag content that should be added to the HTML header.
FooterAdditions	Collection(string)	A list of tag content that should be added to the end of the HTML body.

TocItem

Name	Value	Description
Title	String	Title (last element in the TocPath) of this page
DocFile	DocFile	Pointer to the internal DocFile class for the source file.
Url	The relative URL to the item this TocItem represents
NextLevel	Collection(TocItem)	Collection of the children for this item.

Additional Mustache Template Tags

In addition to the standard Mustache template language tags, the following tags have been added to APIDocs to enable additional scenarios when publishing static HTML from Markdown:

Tag Name	Description	Example
{{#IfMatch valueA valueB }}	Content block tag that allows enabling the output of content if the two values provided are equal.	{{#IfMatch Page.Section 'documentation'}}This is the documentation section!{{/IfMatch}}
{{#ElseMatch}}	Allows an else clause for IfMatch tags if the match fails.
{{#url 'page-name.htm'}}	Replace tag with a relative URL to the root of the output folder. Allows you to reference content from anywhere in the hierarchy consistently in the template	<img src="{{#url 'images/foo.jpg'}}">

Swagger2

You can publish the documentation as a Swagger2 API definition using the swagger2 format. This attempts to parse the structure of the documentation and build a Swagger file from the docs.

Support for publish as Swagger2 is limited. This feature needs work.

The following additional command line options are required for swagger2 output:

Name	Description
--swagger-title	Title of the API in the Swagger header .
--swagger-description	Description of the API in the Swagger header.
--swagger-version	Version number (1.0) in the Swagger header.
--swagger-auth-scope	Set the required auth scope for every method in the Swagger output.