Markdown Syntax

Configuring Markdig​

Razor Press uses the high-quality Markdig CommonMark compliant implementation for its Markdown parsing in .NET.

Each Markdown*.cs feature is able to customize which Markdig features it wants to use by providing a custom CreatePipeline() implementation with all the Markdig extensions it needs.

Alternatively the Markdig pipeline can be globally extended for all Markdown features by adding it to MarkdigConfig pipeline in Configure.Ssg.cs:

MarkdigConfig.Set(new MarkdigConfig
{
    ConfigurePipeline = pipeline =>
    {
        // Extend Markdig Pipeline
    },
    ConfigureContainers = config =>
    {
        config.AddBuiltInContainers();
        // Add Custom Block or Inline containers
    }
});

Header Anchors​

Headers, like above, automatically get anchor links applied with an id that's automatically generated from the Header text.

Custom Anchors​

To specify a custom anchor tag for a heading instead of using the auto-generated one, add a suffix to the heading:

### Custom Anchors {#my-anchor}

This allows you to link to the heading as #my-anchor instead of the default #custom-anchors.

Custom Classes​

Custom Classes can be added to headings with the suffix:

### Custom Classes {.my-class}
### Custom Classes {#my-anchor .my-class .my-class2}

However to override the default @tailwindcss/typography styles applied to headings they'll need to included within a not-prose class which can be done with:

:::{.not-prose}
## Custom Class {.text-5xl .font-extrabold .tracking-tight .text-indigo-600}
:::

Which generates the HTML:

<div class="not-prose">
    <h2 id="custom-class" class="text-5xl font-extrabold tracking-tight text-indigo-600">
        Custom Class
    </h2>
</div>

To render it with the custom tailwind styles we want:

Document Map​

A Document Map is created for each Markdown document from its Heading 2 and Heading 3 headings, e.g:

## Heading 2
### Heading 3
### Heading 3a

## Heading 2a

Which populates the MarkdownFileInfo.DocumentMap collection that renders the Document Map on the right column of each document, that's displayed in devices with larger resolutions that can fit them.

The document map also makes use of the Auto heading anchors for its navigation, that's kept updated as you scroll.

GitHub-Style Tables​

Many GitHub Flavored Markdown syntax is also supported in Markdig like their ASCII Tables, e.g:

Input​

| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |

Output​

Which can be further styled with custom classes:

Input​

:::{.not-prose .table .table-striped}
| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |
:::

Output​

Syntax Highlighting in Code Blocks​

Razor Press uses highlight.js to highlight code blocks allowing you to add syntax highlighting using the same syntax as GitHub Code Blocks, e.g:

Input​

```csharp
class A<T>
{
    public string? B { get; set; }
}
```

Output​

class A<T>
{
    public string? B { get; set; }
}

Input​

```json
{ "A": 1, "B": true }
```

Output​

{ "A": 1, "B": true }

Markdown Fragments​

Markdown fragments should be maintained in _pages/_include - a special folder rendered with Pages/Includes.cshtml using an Empty Layout which can be included in other Markdown and Razor Pages or fetched on demand with Ajax from /includes/vue/formatters.

Includes​

Markdown Fragments can be included inside other markdown documents with the ::include inline container, e.g:

::include vue/formatters.md::

Where it will be replaced with the HTML rendered markdown contents of markdown fragments maintained in _pages/_include, which in this case embeds the rendered contents of _include/vue/formatters.md.

Include Markdown in Razor Pages​

Markdown Fragments can be included in Razor Pages using the custom MarkdownTagHelper.cs <markdown/> tag:

<markdown include="vue/formatters.md"></markdown>

Inline Markdown in Razor Pages​

Alternatively markdown can be rendered inline with:

<markdown>
## Using Formatters

Your App and custom templates can also utilize @servicestack/vue's
[built-in formatting functions](href="/vue/use-formatters).
</markdown>