# Content Authoring

URL: /bengal/docs/build-sites/write/authoring/
Section: authoring
Tags: persona-writer

--------------------------------------------------------------------------------

Writing Content Write in CommonMark Markdown and extend with 60+ MyST directives for tabs, callouts, code blocks, and interactive components. Note Note Do I need this? Yes when authoring rich docs content. Start with Writer Quickstart if you have not scaffolded a site yet. For directive syntax lookup, see Directive Kitchen Sink. File Linking Guide Markdown links, cross-references, anchors, and target directives File Linking Reference Template link functions, path resolution, and linking best practices File External References Link to external documentation like Python stdlib, NumPy, and other Bengal sites Code Code Blocks Add syntax-highlighted code with Rosettes, include files, configure themes, and create multi-language examples Code Code Blocks Reference Multi-language code tabs, Rosettes syntax themes, and advanced options Images & Media Add images, figures, videos, and embeds to your content Function Math and LaTeX Inline and block mathematical expressions with LaTeX Tables Create simple and complex tables using pipe syntax, list-table directive, and interactive data-tables Info Callouts & Admonitions Draw attention to important information with notes, warnings, and tips Interactive Elements Create tabs, dropdowns, steps, and other interactive content Quick Reference Text Links Math Code Callouts **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]] $E = mc^2$ $$ \sum_{i=1}^n x_i $$ {math}`\frac{a}{b}` ```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 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 via params 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 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 Info Seealso Directives Reference — Complete directive documentation Icon Reference — Available icons

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 529
- Reading Time: 3 minutes