Markdown Content Help File Format

The Markdown help format is used to produce content that can be viewed on websites that can transform markdown files into HTML. The presentation style supplied with the help file builder renders GitHub flavored markdown content suitable for use on GitHub project wikis. However, there are some known issues and limitations as noted below.

If these limitations are not acceptable, it is suggested that you generate the content as a true website and host it somewhere such as the GitHub Pages site related to your project rather than the wiki.

• The markdown format works best for projects with a small number of conceptual topics and API members. Sites like GitHub render a sidebar which, for large projects, can become cumbersome to use when the content is deeply nested. You will have to be the judge as to whether or not the generated content is suitable for use on a markdown website.

• As noted, the markdown generated is geared towards GitHub flavored markdown. Results may vary on other sites.

    Important

  The content generated is specifically for wiki sites. It will not work properly if checked into a source repository and viewed from the source code browser.

• Code colorization is left to the markdown processor provided it knows how to handle fenced code blocks. The line numbering and collapsible region features of the code block component are not supported. Those features will be ignored.

• Obviously, the language filter from the HTML help formats is not supported. As such, language-specific text is shown using the generic, multi-language style. Likewise, syntax sections and code blocks are shown in a sequential fashion similar to the topic previewer.

• Markdown processors make certain assumptions about the text based on the way it is formatted which do not always hold true for the content generated by the presentation style. In addition, certain HTML elements must be formatted very specifically to work around issues in the markdown processors. On GitHub for example:

  • Table cells written in markdown cannot span multiple lines.

  • List items written in markdown cannot contain multiple paragraphs.

  • Markdown elements embedded within certain HTML elements (i.e. HTML list items and table cells elements) may not get processed in all cases.

  • Various HTML block elements such as tables and lists must be preceded and followed by a non-breaking space or the markdown processor may ignore markdown elements within the block elements.

  As such, a lot more HTML is generated by the presentation style than you would see if it was written by hand to work around such limitations since the presentation style cannot assume the content fits the layout requirements expected by the markdown processors.

• Address anchors on elements such as list items and table cells are not supported as GitHub strips most attributes from elements. Links to title elements and the introduction (page header) are supported.

• "No Bullet" style lists and image placement options are not supported as GitHub strips the style attribute from all elements.

• Literal HTML in conceptual topics and XML comments may not be rendered as expected since the markdown processor strips most attributes from the elements (id, style, etc.).

• It is not possible to check for and escape every possible markdown directive in conceptual topic text and XML comments text. As such, certain constructs may be interpreted as markdown and rendered differently. For example, if your comments contain the literal text *Some text surrounded by asterisks*, it will most likely be rendered as emphasized text rather than literal text in asterisks as it would in website output.

• GitHub uses the filename as the page title. Topics will continue to use the selected naming method and, as such, you will see that filename at the top of each page. The topic title rendered by the presentation style will appear below it. This may not be ideal but is necessary. The topic title cannot be used as the filename since they need to be unique across all topics documented. For example, if Class1 appeared in two separate namespaces and the topic titles were used as filenames, the topics from one of the classes would overwrite the other. Fully qualifying the names and including parameter information would allow them to be unique but would most likely result in extremely long filenames that could exceed the maximum filename length limit.

• GitHub expects there to be a Home.md topic within the site. If one does not appear, a copy of the default topic is made and named Home.md to satisfy this requirement. If your project contains a Home.md file included as content in the root of your project or in a site map file, it will be copied to the build output and used instead.

• Conceptual topics can be written in markdown, saved as .md files, and included in the project. However, they must be saved to the root folder of the project, their Build Action property must be set to Content, and they must be included in a site map file if you want them to appear in the table of contents (sidebar) generated by the build.

• A page header is not supported and the page footer is a separate file in markdown content. As such, localized resource items cannot be used within the footer. A default _Footer.md file containing the help title, the additional footer information property content, the copyright URL, and contact e-mail address is included by default.

    Tip

  As in other help file formats, stock content file overrides are supported. Including a Home.md and/or _Footer.md file containing appropriate content in your project's root folder with the Build Action set to Content will override the default home page and/or footer in the generated content.

Other Resources