Content Authoring

Markdown, MyST directives, and shortcodes

1 page in this section

Bengal uses CommonMark Markdown with MyST extensions for rich documentation.

Quick Reference

1
2
3
**bold** and *italic*
~~strikethrough~~
`inline code`

1
2
3
[External](https://example.com)
[Internal](/docs/get-started/)
[Relative](../other-page/)

1
2
![Alt text](/images/hero.jpg)
![With title](/images/hero.jpg "Title")

1
2
3
4
```python
def hello():
    print("Hello!")
```

With line highlighting:

1
2
3
4
```python {hl_lines="2"}
def hello():
    print("Highlighted!")
```

MyST Directives

Directives add rich components to your Markdown:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
:::{note}
Informational callout.
:::

:::{warning}
Important warning!
:::

:::{tip}
Helpful suggestion.
:::

1
2
3
4
5
6
7
8
:::{tab-set}
:::{tab} Python
print("Hello")
:::{/tab}
:::{tab} JavaScript
console.log("Hello")
:::{/tab}
:::{/tab-set}

1
2
3
4
5
6
:::{cards}
:::{card} Title
:link: ./path/
Description here
:::{/card}
:::{/cards}

1
2
3
4
5
:::{dropdown} Click to expand
:icon: info

Hidden content here.
:::

1
2
3
4
5
6
7
8
:::{youtube} dQw4w9WgXcQ
:title: Video Title
:::

:::{figure} /images/diagram.png
:alt: Architecture diagram
:caption: System overview
:::

Syntax Overview

flowchart LR A[Markdown] --> B[MyST Parser] B --> C{Directive?} C -->|Yes| D[Render Component] C -->|No| E[Render HTML] D --> F[Final Page] E --> F

Tip

Most common: Admonitions (note,warning,tip) and code blocks with syntax highlighting. Start there, add tabs and cards as needed. For visual elements, see the Icon Reference for inline SVG icons.

Variable Substitution

Use{{ variable }}syntax to insert frontmatter values directly into your content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
---
product_name: Bengal
version: 1.0.0
beta: true
---

Welcome to **{{ product_name }}** version {{ version }}.

{% if beta %}
:::{warning}
This is a beta release.
:::
{% endif %}

Available Variables

Variable Source Example
{{ page.title }} Current page {{ page.title }}
{{ page.description }} Current page {{ page.description }}
{{ product_name }} Frontmatter Direct access to any frontmatter key
{{ params.key }} Frontmatter Hugo-style access viaparams
{{ site.title }} Site config {{ site.title }}
{{ config.baseurl }} Site config {{ config.baseurl }}

Cascaded Variables

Variables cascade from parent sections. Set them once in a section's_index.md:

1
2
3
4
5
6
7
# docs/api/_index.md
---
title: API Reference
cascade:
  api_version: v2
  deprecated: false
---

Then use in any child page:

1
2
# docs/api/users.md
This endpoint uses API {{ api_version }}.

Tip

Common use cases: Product names, version numbers, feature flags, environment-specific values, and cascaded metadata like API versions or status badges.