Writing documentation with human-readable markdown

This guide explains how to write and maintain documentation using plain markdown that stays easy to read at source while supporting rich layouts and interactivity.

We use GitHub-flavored markdown (GFM) with a few lightweight, intuitive extensions for:

• ✅ Callouts
• ✅ Tabs
• ✅ Cards
• ✅ Columns
• ✅ Toggles
• ✅ Boxed sidebars
• ✅ Bookmarks
• ✅ Buttons
• ✅ Steps

Everything renders beautifully without breaking readability for humans or editors.

Frontmatter

Each markdown file can include optional YAML frontmatter at the top to control metadata and behavior.

---
title: Your Page Title
description: A brief description of this page
searchable: false
section: plugins
doc-type: doc
hide-toc: true
youtube-video: dQw4w9WgXcQ
---

Standard fields

• title (optional): The page title displayed in navigation and search results
• description (optional): A summary shown in search results and metadata

Custom fields

• searchable (optional, defaults to true): Set to false to exclude this page from search indexing
• section (optional): Categorizes the page for filtered search (e.g., core, plugins, theme)
• doc-type (optional): Controls the page layout theme
• home – for landing or overview pages
• doc – for standard documentation pages
• hide-toc (optional): Set to true to hide the "On this page" sidebar navigation
• youtube-video (optional): YouTube video ID to embed a mini player in the sidebar (e.g., dQw4w9WgXcQ)

Example

---
title: Getting Started with Tabs
description: Learn how to create tabbed content in your documentation
section: core
doc-type: doc
youtube-video: abc123xyz
---

1. Callouts

GitHub-flavored callouts work natively using the > [!TYPE] pattern.

> [!NOTE]
> This endpoint requires authentication via headers.
>
> Example: TGX-API-KEY

Supported types

• [!NOTE] – default callout style
• [!INFO] – informational callout
• [!TIP] – helpful tips and suggestions
• [!IMPORTANT] – important information to note
• [!WARNING] – warnings about potential issues
• [!CAUTION] – cautionary notices
• [!DANGER] – critical warnings about dangerous actions

Each will render with its own visual style.

2. Tabs

Tabs group related content (for example, code snippets in multiple languages).

<div class="tab-group">
<nav>
  <button class=" active-tab" type="button" data-target="python">python</button>
  <button class="" type="button" data-target="javascript">javascript</button>
</nav>
<div class=" active-tab" data-id="python">
‘‘‘python
print("Hello, World!")
‘‘‘
</div>
<div class="" data-id="javascript">
‘‘‘js
console.log("Hello, World!")
‘‘‘
</div>
</div>

Rules:

• text after "tab" defines the tab’s title.
• Spaces are converted to - for the tab’s internal ID.
• If no label is provided, tabs default to tab-1, tab-2, etc.
• If all tabs contain only fenced code blocks, the container renders with
  .

3. Cards

Cards highlight small pieces of information, previews, or summaries.

Chat window

The main area where users talk to your bot.

> [!TIP]
> You can combine **callouts** with cards, tabs, or toggles for richer docs.

<div class="tab-group">
<nav>
  <button class=" active-tab" type="button" data-target="label=&quot;python&quot;">label=&quot;python&quot;</button>
  <button class="" type="button" data-target="label=&quot;javascript&quot;">label=&quot;javascript&quot;</button>
</nav>
<div class=" active-tab" data-id="label=&quot;python&quot;">
‘‘‘python
print("Hello")
‘‘‘
</div>
<div class="" data-id="label=&quot;javascript&quot;">
‘‘‘js
console.log("Hello")
‘‘‘
</div>
</div>


More examples
<div class="cols" style="--md-cols:2">


Feature 1: fast setup



Feature 2: human-readable markdown


</div>