API Doctor implements the following additional features on top of the Markdown language.
Tagging of content allows the author to include sections that are conditionally included or omitted based on the parameters passed at build time. This allows one set of source files to generate content for multiple targets.
To tag content, wrap the Markdown to tag with the following tags:
[TAGS=<Comma-delimited list of tags>]
Some Markdown content here
[END]
This will cause everything between the start [TAGS] line and the ending [END] line to only be included in the final output if one or more of the tags in the comma-delimited list are specified at build time.
Included content will be wrapped with <div> tags with a class attribute set based on the tags. The class value takes the form content-<TAG VALUE>. So a Markdown marker of [TAGS=FOO] would result in <div class="content-foo">.
There are some limits to what you can do with this.
[TAGS] marker and the [END] marker must be on their own line. You cannot insert them in the middle of a paragraph.To specify tags at build time, the --parameters parameter must include a TAGS key, with the value set to a comma-delimited list of tags to include. For example:
apidoc.exe publish --format html --path .\src --output .\out --parameters "TAGS=OUTLOOK,v2"
Let’s take a look at a simple example. Suppose you have the following Markdown source file:
# Tagging Demo
This content should always appear in the output because it is not tagged.
[TAGS=V1]
This is v1 content, and only appears if the V1 tag is specified at build.
[END]
[TAGS=V2]
This is v2 content, and only appears if the V2 tag is specified at build.
[END]
[TAGS=V1,V2]
This is v1 and v2 content, and only appears if either the V1 or V2 tags are specified at build. Also appears if both tags are specified.
[END]
If the --parameters parameter is omitted, or does not contain a TAGS key, or the TAGS key does not contain a V1 or V2 value, the following is the result:
<h1 id="tagging-demo">Tagging Demo</h1>
<p>This content should always appear in the output because it is not tagged.</p>
If the --parameters parameter is set to TAGS=V1, the following is the result:
<h1 id="tagging-demo">Tagging Demo</h1>
<p>This content should always appear in the output because it is not tagged.</p>
<div class="content-v1">
<p>This is v1 content, and only appears if the V1 tag is specified at build.</p>
</div>
<div class="content-v1 content-v2">
<p>This is v1 and v2 content, and only appears if either the V1 or V2 tags are specified at build. Also appears if both tags are specified.</p>
</div>
Use the following syntax to include another Markdown file.
[INCLUDE [<name of file>](path to file)]
For example:
[INCLUDE [included-file.md](includes/included-file.md)]
You can construct paths to include files as either relative to the root of the documentation set, or relative to the current file.
Paths that start with a / are considered relative to the root of the documentation set.
[INCLUDE [included-file.md](/includes/included-file.md)]
Paths that start with one or more ., or alpha-numeric characters, are considered relative to the current file.
[INCLUDE [included-file.md](./includes/included-file.md)]
[INCLUDE [included-file.md](includes/included-file.md)]