Writing and formatting MDX content

The quality of MDX content depends on more than valid syntax. The document should also read well, scan well, and render consistently.

Use headings to express structure

A page title is handled by the page template. The MDX body normally starts with second-level headings. Use third-level headings when a section genuinely has subtopics. Do not skip heading levels just to change font size.

Write full paragraphs

Our content standard favors normal paragraphs with connected reasoning. We avoid the pattern where every sentence becomes its own paragraph because it creates artificial drama and makes technical writing harder to read.

Lists are for list-shaped information

Lists are useful for steps, requirements, options, or grouped details. They should not replace ordinary prose when explanation matters.

Code belongs in fenced blocks

Technical examples should use fenced code blocks so they are readable and horizontally scrollable on small screens.

Links should explain their destination

Anchor text should describe what the reader will find. "Read our web development service" is more useful than "click here."

Avoid layout hacks inside content

Do not use repeated line breaks, inline style attributes, or custom HTML just to force spacing. The stylesheet owns typography and rhythm.

Keep the content portable

One advantage of MDX is that the source remains readable as text. We protect that advantage. A content file should still make sense if someone opens it in a code editor without the site running.

The renderer already supplies part of the document structure

Our article and documentation templates normally render the page title outside the MDX body. That means the body should begin at the next heading level rather than introducing another H1. At least one production article system enforces this two ways: the renderer maps body-level H1 elements to H2, and a validation script checks that the mapping remains in place. We would rather encode the rule than rely entirely on every future writer remembering it.

Paragraph rhythm matters

Technical writing needs enough space to breathe without turning every sentence into a dramatic standalone line. We prefer paragraphs that keep related reasoning together, especially when the point depends on a cause-and-effect relationship. Short paragraphs are fine when the idea changes. Constant one-sentence stacking is not our default because it makes long technical material feel artificial and harder to scan.

The visual system already creates spacing between paragraphs and headings. The copy does not need extra blank lines to manufacture emphasis.

Markdown should remain readable before rendering

A useful test is whether the source still makes sense in a code editor. Headings should describe sections. Lists should look like lists. Code examples should be fenced. Links should identify their destinations. We avoid embedding large amounts of custom JSX into ordinary editorial files unless the content genuinely needs a component. The more layout logic enters the MDX, the more the file stops behaving like a portable document.

Code examples should be small enough to teach the point

Documentation is not improved by pasting an entire production component when five lines explain the pattern. We use focused snippets and then describe the surrounding behavior in prose. That protects both readability and maintainability. A huge copied snippet becomes stale quickly, while the source of truth remains in the repository.

Formatting is part of accessibility

Heading order, descriptive links, properly marked lists, and readable code blocks are not merely style preferences. They help assistive technology interpret the document and help keyboard and screen-reader users understand its structure. The MDX source is the first place that structure is expressed, so content formatting participates in the accessibility standard rather than sitting outside it.