Skip to content

04. Markdown Pages

Jump to bottom
James231 edited this page Jun 9, 2020 · 2 revisions

This section describes creating a Markdown .md page in the Input folder which will become a page of the documentation (a .html page) when the tool is run. The Documentation Templator uses the Markdig package to convert the Markdown to HTML. Since the Markdown files are converted to HTML you can also use the full HTML feature set within them.

Just like HTML pages, Markdown pages support using Page Properties (different syntax) and Template Elements.

Out of the box, Markdown pages support all of the common markdown features (e.g. headings, emphasis/superscript/underlines/strikethroughs, links, lists, tables, codeblocks, blockquotes, ... etc).

Page Properties

Recall from the section on HTML pages that a Page Property has a name and a value, where the value can be injected into the Page Template. They are useful for page metadata to be displayed outside of the @ChildContent; in the page template.

In Markdown page properties should be at the top of the file, each on a new line. Each property should start with Property: followed by the property name, then a comma , followed by the property value.

Page Property Example

Suppose this is our Markdown file in the Input folder

Property: PageTitle, My Super Page
Property: LastEdit, 6th June 2020

Some **markdown** code.

And suppose we have the following Page.html template file:

<html>
    <body>
        <h3>@Page.PageTitle;</h3>
        <p>Last Edit: @Page.LastEdit;</p>
        @ChildContent;
    </body>
</html>

Then the output page consists of the following HTML:

<html>
    <body>
        <h3>My Super Page</h3>
        <p>Last Edit: 6th June 2020</p>
        Some <strong>markdown</strong> code.
    </body>
</html>

Template Elements

As Markdown pages are converted to HTML, you can use HTML tags within the Markdown. And just like HTML pages this includes being able to use Template Elements (i.e. Custom Controls). For example you can create a control <card> ... </card> Template elements can have multiple inputs including child content. See this page on Template Elements for more information.

Additional Markdown Features

One of the benefits of using Markdig to convert Markdown to HTML is that is easy to extend if you want additional Markdown features. By adding just a few lines to the source code of the Documentation Templator (here) you can add extensions. Some existing extensions you can use include:

  • LaTeX support
  • Citations
  • Soft and Hard Lines
  • Figures and Diagrams
  • Footnotes
  • Media Support, e.g. YouTube (although you could use iframe tags anyway)

See the Markdig Github Page for a more complete list.

Enjoying using Documentation Templater? Make sure you ⭐ the repo!!!

Clone this wiki locally