Markdown extensions catalog

The catalog of non-CommonMark Markdown features enabled in Pennington's Markdig pipeline. Markdig's own built-in syntax (tables, footnotes, and so on) is not covered here.

Tabs

Renders a run of consecutive fenced code blocks (starting with one that carries tabs=true) as a single tabbed container with role="tablist", role="tab", and panel regions. The first tab is active by default.

Syntax

```csharp tabs=true title="C#"
// block A
```

```razor title="Razor"
@* block B *@
```

Each fenced block in the consecutive run becomes a tab panel; only the first block requires tabs=true to open the group.

Arguments

Arguments are key=value pairs; quoted values are allowed. See Code-block argument reference for the full grammar.

Emitted CSS classes

Classes are configurable via TabbedCodeBlockRenderOptions passed to UseTabbedCodeBlocks.

Minimal example

Markdown source showing a two-fence tabbed group:

---
title: Authoring a doc page
description: Populate DocSiteFrontMatter, add an alert, and group code samples into tabs.
tags:
  - authoring
  - front-matter
  - markdown
sectionLabel: Guides
order: 20
---
  
# Authoring a doc page
  
## Callouts
  
> [!NOTE]
> Alerts render with a coloured left border and an icon matching the kind.
  
## Tabbed code groups
  
```bash tabs=true title="dotnet CLI"
dotnet add package Pennington
```
  
```powershell title="PowerShell"
Install-Package Pennington
```
  
```xml title="csproj"
<PackageReference Include="Pennington" Version="*" />
```

Content tabs

Groups a run of DocFX-style tab headings into a single tabset whose panels hold arbitrary Markdown — prose, lists, code, callouts. Distinct from tabbed code: the tab strip sits in the reading flow rather than inside code chrome.

Syntax

A tab opens with a level-1 heading whose only inline is a link to #tab/<id>; the link text is the button label. Consecutive tab headings form one group, ended by a thematic break (---).

# [Bash](#tab/bash)

Use the bash variant.

# [PowerShell](#tab/pwsh)

Use the PowerShell variant.

---

Dependent tabs

A third path segment — #tab/<id>/<condition> — gates the tab on another group's selection. <condition> is a tab id that has its own plain group elsewhere on the page; the dependent panel shows only when its <id> is the active button and its <condition> is that other group's selected id.

# [.NET](#tab/lang/linux)

.NET on Linux.

# [.NET](#tab/lang/windows)

.NET on Windows.

---

Arguments

Emitted CSS classes

The first panel is active in the server-rendered HTML; the client script recomputes selection on load, syncs equal ids page-wide, and persists each choice in localStorage.

Minimal example

A two-tab group whose panels hold prose; the --- thematic break closes the set:

# [Bash](#tab/bash)

Run the bash script.

# [PowerShell](#tab/pwsh)

Run the PowerShell script.

---

Includes

Splices a referenced Markdown file into the host page during parsing. The directive works as a standalone block or inline within a sentence; the referenced file is expanded recursively.

Syntax

[!INCLUDE [block partial](../_includes/partial.md)]

Text before [!INCLUDE [inline partial](../_includes/snippet.md)] and after.

Arguments

Behavior

Relative links and images inside an included file are not rebased — they resolve as if written in the host page.

Minimal example

A standalone block include splicing a shared partial into the host page:

[!INCLUDE [install steps](../_includes/install.md)]

Alerts

Parses a GitHub-flavored > [!KIND] token as the first line of a blockquote and emits an AlertBlock with two CSS classes. The blockquote form is the only accepted syntax.

Syntax

> [!NOTE]
> Body text of the alert, CommonMark rendered.

KIND is a case-insensitive alphabetic token.

Arguments

Built-in kinds and emitted CSS classes

Every alert receives two classes: markdown-alert (constant) and markdown-alert-<kind>.

Minimal example

Markdown excerpt showing a [!NOTE] block in context:

---
title: Authoring a doc page
description: Populate DocSiteFrontMatter, add an alert, and group code samples into tabs.
tags:
  - authoring
  - front-matter
  - markdown
sectionLabel: Guides
order: 20
---
  
# Authoring a doc page
  
## Callouts
  
> [!NOTE]
> Alerts render with a coloured left border and an icon matching the kind.
> Supported kinds include `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and
> `CAUTION`.

Code annotations

After syntax highlighting, each rendered line is scanned for a [!code …] directive inside a language-appropriate comment. The directive is stripped and a CSS class is applied to the line (and optionally to the enclosing <pre>). The word: variant wraps a matching substring; the include-start/include-end/exclude-start/exclude-end directives remove surrounding lines from the output.

Syntax

```csharp
var x = 1; // [!code highlight]
var y = 2; // [!code ++]
var z = 3; // [!code word:z|renamed from q]
```

The directive must appear inside a comment marker recognized for the language; the marker and any now-empty comment wrapper are removed, leaving trailing content intact. Code-block argument reference is the canonical reference for the full directive set (highlight, ++/--, focus, error, warning, word:, the include/exclude region markers) and the recognized comment markers.

Emitted CSS classes

Line-level classes (highlight, diff-add, diff-remove, focused / blurred, error, warning) are added to the <span class="line"> wrapper. Block-level classes (has-highlighted, has-diff, has-focused, has-errors, has-warnings, has-word-highlights) are added to the outer <pre>. The word: notation emits word-highlight or word-highlight-with-message on the wrapped span, plus the callout elements word-highlight-wrapper, word-highlight-message, word-highlight-arrow-container, word-highlight-arrow-outer, and word-highlight-arrow-inner.

Minimal example

An annotated fence exercising [!code highlight], [!code ++], and [!code --]; the enclosing <pre> receives has-highlighted and has-diff, and the trailing directive comments are stripped from the emitted HTML:

```csharp
var message = "hello";   // [!code highlight]
var added = "added";     // [!code ++]
var removed = "gone";    // [!code --]
```

Cross-reference tags

xref: links resolve after rendering against the uid-to-route map built from every page's front-matter uid:. Two surface forms are supported: the tag form <xref:uid> and the attribute form [text](xref:uid). Unknown uids emit a diagnostic that surfaces in the dev overlay and in the static-build report.

Syntax

See <xref:reference.api.pennington-options>.

See [PenningtonOptions](xref:reference.api.pennington-options).

uid is the exact string declared in a page's front-matter uid: key.

Arguments

Emitted CSS classes

The rewriter emits a standard <a href="…"> element with no added class; styling is delegated to the surrounding prose stylesheet.

Minimal example

Both surface forms resolving the same uid — the tag form derives its link text from the target page title, the attribute form uses the supplied label verbatim:

See <xref:reference.api.pennington-options> for the full options catalog.

Configure MonorailCSS through [the options record](xref:reference.api.monorail-css-options).

Shortcodes

Shortcodes run before Markdig parses the page rather than as a Markdig extension: each <?# Name args /?> directive is expanded to text or HTML first by a registered IShortcode handler, and the result flows through the pipeline as ordinary markdown. Names are case-insensitive.

Syntax

A call has a self-closing form and a block form with inline content:

<?# Name positional key="value" /?>

<?# Name ?>inline content<?#/ Name ?>

To document a directive without expanding it, prefix the opener with a backslash — the expander emits the directive verbatim. (Every literal directive on this page uses that escape.)

Built-ins

Unknown names and handler failures degrade to an HTML comment plus a warning diagnostic, so one bad call site never fails the render. See the shortcodes how-to for the handler contract and registration.

See also

• How-to: Add a Markdig extension or inline parser — register syntax this catalog doesn't list
• How-to: Tabbed code
• How-to: Content tabs
• How-to: Reuse shared content
• How-to: Alerts
• How-to: Code annotations
• How-to: Cross-references
• How-to: Expand a directive before Markdig parses
• Related reference: Code-block argument reference