Documentation components
Visual reference for Markdown and documentation-specific MDX components
Documentation components
This page shows how regular Markdown and documentation-specific components look for content authors. Use it as a visual reference before creating a new public documentation page.
Basic Markdown
Text
Documentation supports regular text, emphasis, outdated fragments, links, and lists.
For example, you can link to the documentation home or open an
external resource in a new tab. Complex terms and notes can move
to footnotes1, so the paragraph stays readable2.
- A bullet list works well for short enumerations.
- Each item should be self-contained and clear.
- If the list grows too long, split it into several blocks.
- A numbered list works well for a sequence of actions.
- Each step should describe one action.
- The result of the step should be explicit.
A quote works well for a principle, agreement, or excerpt from a user scenario.
Short values can stay inline: status: "published", group: "Documentation", or
parentItem: "Authoring".
Images
Template logo
Template app icon
Code block
---
title: "Page title"
description: "Short page description"
group: "General"
parentItem: "Authors"
order: 30
status: "draft"
toc: true
---
Tables
| Field | Type | Purpose |
|---|---|---|
title | string | Page title shown in the header and left menu |
description | string | Page subtitle and search description |
order | number | Page position inside parentItem |
status | string | Page status: draft, review, published, or archived |
hide | boolean | Hides the page in production for every status |
toc | boolean | Enables the right column with page section navigation |
Checklists
Checklists are useful for page acceptance before publishing:
- Fill frontmatter and verify
groupandparentItem - Check that second-level headings appear in the right navigation
- Align the description with a stakeholder
- Move the page to publication with
status: "published"
Highlighted notes
Use this block for an important explanation that should stand out more than a normal paragraph.
Additional information that helps readers understand the scenario but does not block the main flow. Use it to link related documents or share a nuance.
Confirmation that a step finished successfully: for example, the page is published, materials are approved, or navigation reflects the change.
Use a warning when an action requires attention: for example, before publishing a page or changing a material status.
Use this variant for errors that block the scenario, or rules where violation can cause data loss.
Step-by-step scenario
Prepare the structure
Choose the section, parent menu item, and page order in navigation.
Fill the content
Start with a short description, then add main sections, examples, and limits.
Check the result
Make sure headings appear in the right navigation and the page appears in the left menu.
File structure
Switchable blocks
Use tabs when you need to show several variants of the same material: description, example, and ready-to-use snippet.
Recommendations for authors
Write a page around one user scenario. If the material starts mixing roles, statuses, instructions, and reference information, split it into several pages and connect them with links.
Start main sections with second-level headings. The right navigation is built from them, so names should be short and recognizable.