Skip to content

Latest commit

 

History

History
112 lines (83 loc) · 7 KB

publishing.md

File metadata and controls

112 lines (83 loc) · 7 KB
Raw

Publishing from Markdown

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

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

API Doctor 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:

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

API Doctor 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).

API Doctor 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 API Doctor 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.