Content Authoring

Markdown, MyST directives, and rich content

3 min read 580 words

Bengal uses CommonMark Markdown with MyST-style directive extensions for rich documentation. Write in standard Markdown and extend with 60+ built-in directives.

What Do You Need?

Links & Cross-References

Create internal links, cross-references, and anchor links.
External References

Link to Python stdlib, NumPy, and other Bengal sites.
Code Blocks

Syntax highlighting, line numbers, and file includes.
Images & Media

Add images, figures, videos, and embeds.
Tables

Simple pipe tables and complex list-tables.
Callouts & Admonitions

Notes, warnings, tips, and collapsible sections.
Interactive Elements

Tabs, dropdowns, steps, and cards.

Quick Reference

**bold** and *italic*
~~strikethrough~~
`inline code`

[External](https://example.com)
[Internal](/docs/get-started/)
[[Cross-reference]] docs/page
[[#heading]] Anchor link
[[ext:python:pathlib.Path]]

```python
def hello():
    print("Hello!")
```

With line highlighting:

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

:::{note}
Informational callout.
:::

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

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

How Content Flows

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

Variable Substitution

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

---
product_name: Bengal
version: 1.0.0
beta: true
---

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

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

Note

Bengal uses Kida templating which supports both{% end %} (unified syntax) and {% endif %}(Jinja-compatible). Use whichever you prefer.

Available Variables

Variable Source Example
Content Authoring Current page Content Authoring
Markdown, MyST directives, and rich content Current page Markdown, MyST directives, and rich content
{{ product_name }} Frontmatter Direct access to any frontmatter key
`` Frontmatter Hugo-style access viaparams
Bengal Site config Bengal
/bengal Site config /bengal

Cascaded Variables

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

# docs/api/_index.md
---
title: API Reference
cascade:
  api_version: v2
  deprecated: false
---

Then use in any child page:

# 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.

Available Directives

Bengal provides 60+ directives organized by category:

Category Directives
Admonitions note, tip, warning, danger, error, info, example, success, caution, seealso
Layout tabs, tab-set, cards, card, child-cards, grid, container, steps, step, dropdown
Tables list-table, data-table
Code code-tabs, literalinclude
Media youtube, vimeo, tiktok, video, audio, figure, gallery
Embeds gist, codepen, codesandbox, stackblitz, asciinema, spotify, soundcloud
Navigation breadcrumbs, siblings, prev-next, related
Versioning since, deprecated, changed
Utilities badge, button, icon, rubric, target, include, glossary, checklist, marimo

Seealso