Authoring Topics Edit on GitHub

To author new topic files, just create textual files with the .md extension (see Creating a Navigation Structure to see how these files are organized into a navigable structure). Storyteller provides a couple levels of transformation from raw textual files to the finished html:

1. Comment directives to override a topic's title or url

2. Storyteller supports several custom preprocessing directives that follow a syntax like <[linkto:topic_key;title=Link to a Different Topic]>

3. Markdown transformation of text to html using the Markdig library.

4. A limited master page template to theme the documentation and provide consistent navigation structures. See Documentation Skinning for more information.

See these topics for more information about custom directives:

• Linking to Other Topics
• Embedding Code Samples
• Documentation Skinning

Topic Titles

Storyteller derives or reads a title for each topic file to use within both the layout.htm and any navigation structures. By default, the title is derived by just capitalizing the "key" of the topic, so the title of a file called colors.md would be "Colors". Likewise, the title of a topic file called /planets/index.md would be "Planets".

To explicitly configure the title, use an html comment at the top of the file like this:

<!--Title:Authoring Topics-->

Topic Urls

The url for a topic is derived by adding a segment to the url of a topic's parent derived from the file name. You can override the last segment of a topic url by adding an html comment to the top of the topic file like this:

<!--Url:authoring-->

Table of Contents for Child Topics

You can embed a table of contents in a tree format for any children topics with this directive:

<!--TableOfContents->

Note that this html is generated by C# code and is hard-coded to use styles based on Bootstrap.

Complete Table of Contents

You can embed a table of contents for the entire documentation site in a tree format with this directive:

<!--FullTableOfContents->