Current
MDX formatting
How Doxa normalizes generated page MDX and which content stays exactly as written
Overview
Doxa writes page MDX in one Markdown style. The formatter runs on pages that the generation agent (Doxabot) writes or updates, before the page is validated. Formatting does not change how a page renders, so readers see the same content whichever style the source uses.
Output style
| Construct | Output |
|---|---|
| Bullet list | - item |
| Ordered list | 1. item |
| Strong and emphasis | **strong** and _emphasis_ |
| Code block | Three backticks, with a language identifier |
| Heading | # style, never underlined (setext) style |
| Thematic break | --- |
| Component attribute | Double quotes, such as type="warning" |
| Component children | Indented two spaces per level, with no blank lines around them |
| Table | Columns padded and aligned |
A component in the generated style looks like this:
## Before you start
- Keep the API key in an environment variable.
- Use the same project for every step.
<Note title="Keep the key private" type="warning">
Never write an API key into a page.
</Note>What formatting leaves unchanged
Some content must survive exactly as written:
Frontmatter. The text between the
---lines at the top of a page is kept as is.JavaScript blocks. A top-level block that contains an
{…}expression, a spread attribute, or animportorexportstatement keeps its original text. Rewriting whitespace inside these blocks could change component props.Invalid MDX. A page whose body does not parse is returned unchanged. The validation step reports the error so you can fix it.
Formatting also keeps the rendered page the same. Parsing a page before and after formatting produces the same result, and running the formatter twice produces the same output as running it once.
Existing pages
Published pages are not rewritten in bulk. A page takes the new style the next time a writer produces it. The renderer accepts both styles, so you do not need to migrate existing content.
Where formatting applies
| Editing path | Behavior |
|---|---|
| Doxabot generations and instruction-driven updates | Pages are formatted before validation. |
| Content editor, Split mode (MDX source) | Text is saved exactly as you type it. |
| Content editor, Write mode (rich text) | Formatting applies only to edited blocks, and this is planned rather than available. |
Validate MDX in Split mode:
Split mode saves your text without reformatting it. Check that the MDX is valid before you save to a branch.