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
| 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. |
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.
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.
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. |
| 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. |
| 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. |
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'}}"> |
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. |