Semantic HTML

All useful content should be represented in the HTML without JavaScript. This ensures crawlers, screen readers, and users on slow connections can access documentation content immediately.

This convention works together with Markdown First: markdown provides a readable source format, and semantic HTML ensures the rendered output is equally accessible to both humans and machines.

Code Blocks

The CodeHighlighter component first renders plain text inside standard <pre><code> elements, then after hydration and entering the viewport, replaces it with rich syntax-highlighted markup.

• Faster HTML parse time. Crawlers and search engines don't need syntax highlighting to understand code, and often discard it entirely.
• Streaming-friendly. In server-rendering scenarios, the plain text can be streamed back immediately while syntax highlighting runs asynchronously.
• Room for all variants. Since the initial HTML is smaller without highlighting markup, there is plenty of space to include every file and variant from a demo as plain text.

The fallback content is what search engines and AI bots see in the initial HTML, making it crucial for SEO and content discovery. fallbackUsesExtraFiles includes all extra files from the selected variant, and fallbackUsesAllVariants includes all implementation approaches (CSS Modules, Tailwind, etc.) in the initial HTML for comprehensive automated indexing.

HAST enhancers add visual annotations (wrapper elements, CSS classes, data-* attributes) without changing the plain text output, so the swap from plain text to highlighted code is seamless.

Type Tables

All exported types should be accessible in the initial HTML. The useTypes hook and its companion useType hook register type metadata into a shared context, but the underlying markup uses semantic elements:

• <dl> for definition-style type listings.
• <table> for tabular prop/type displays, with inline <code> elements for type signatures highlighted by transformHtmlCodeInline.
• <a> tags linking related types so crawlers can understand how pages relate to one another programmatically. When a type hasn't been registered in a TypesDataProvider, the TypeRef component falls back to a plain link rather than an interactive popover.

Testing by Disabling JavaScript

If your site functions at a basic level without JavaScript, it's a good indication that crawlers have access to all the same information. Try disabling JavaScript in the browser and verifying that:

• Code blocks display readable source in <pre><code> elements.
• Type tables remain navigable with <table> and <dl> markup.
• Internal links resolve correctly as standard <a> tags.
• Demo content appears as plain text rather than empty containers.

Related

• Markdown First — the source-format counterpart to this convention
• CodeHighlighter — the component that implements progressive code rendering
• HAST — the intermediate format that preserves semantic structure