Write MDX Docs Pages That Follow the Site's Rules and Build Cleanly
Use when an AI writes or edits pages on a documentation site made of MDX files. It puts files in the right folders, fills in the required page settings, avoids MDX syntax mistakes, handles links, images, and redirects, and runs the site's checks before calling a page ready.
To use this AI rule
## Learn How the Docs Site Is Organized Before Writing
Treat the repository as a schema-driven documentation application, not a loose collection of Markdown files.
Identify the site generator, documentation theme, component framework, package manager, runtime version, and deployment target.
Install dependencies with the repository's locked, reproducible command.
Keep runtime and package-manager versions aligned with repository metadata.
Confirm the primary contribution branch rather than assuming a conventional name.
Distinguish user-facing pages, reusable partials, changelogs, glossary data, product metadata, and other structured collections.
Keep custom components, content schemas, Markdown plugins, code-highlighting plugins, icons, assets, styles, and dynamic routes in their designated layers.
Treat static public files differently from images processed by the site generator.
Use the central component export module as the public import surface for MDX.
Keep collection schemas as the authority for accepted fields and value types.
Treat generated skill or reference directories as build products.
Do not edit generated directories or commit ignored generated content.
Read nested instructions before changing a specialized review bot or deployment worker.
Use repository-specific style, component, and procedure references as canonical guidance.
Do not let generic Markdown habits override the site's MDX and schema rules.
## Put Pages in the Right Folders and Name Files Correctly
Put documentation pages under the product or subject directory for user-facing docs.
Put reusable snippets in the partials collection.
Put changelog entries in the matching product or subject subdirectory.
Put glossary terms and other structured metadata in their schema-owned collections.
Require an index page in every navigable content folder when the site expects one.
Use lowercase filenames with words separated by dashes.
Limit content directories to the explicitly allowed text and data extensions.
Typical allowed types are MDX, JSON, YAML, and plain text.
Let extension validation enforce the whitelist instead of hiding unsupported files.
Do not place images or arbitrary binaries inside schema-scanned content directories.
Put processable images in the dedicated asset tree for optimization.
Put truly static files in the public tree only when they must be served unchanged.
Keep directory names aligned with existing product metadata.
Do not create a changelog or collection subdirectory for an unknown product key.
Preserve established collection boundaries instead of inventing a parallel content location.
When moving a page, update inbound links, navigation metadata, redirects, and related partial references.
## Fill In the Page Settings (Frontmatter) the Site Requires
Give every documentation page a frontmatter block that satisfies its collection schema.
Provide a concise page title.
Provide a search description whenever the selected content type requires it.
Choose the page type from the repository's allowed enum.
Common types include concept, configuration, example, FAQ, getting started, how-to, integration, implementation, overview, reference, release notes, solution, troubleshooting, and tutorial.
Use specialized types such as design guide, learning unit, navigation, reference architecture, and video when the schema provides them.
Use sidebar order only when explicit ordering is needed.
Use a sidebar label only when navigation text should differ from the page title.
Reference products or subjects through existing metadata keys.
Use the documented difficulty enum for tutorial content.
Record review dates in the required year-month-day format.
Do not invent schema fields or enum values.
Keep YAML indentation and list structure valid.
Regenerate content-collection types after changing collection definitions or schemas.
Validate data files against their schema rather than relying on visual inspection.
Keep page metadata synchronized when the page's purpose, product, title, or review status changes.
## Write MDX Pages That Build Without Syntax Errors
Follow the repository's canonical writing and formatting guide.
Treat MDX as Markdown plus an embedded component language with stricter parsing.
Escape or code-format brace and angle-bracket characters when they are prose.
Remember that MDX interprets those characters as expressions or components even inside prose.
Import every component used by the page.
Place imports immediately after frontmatter and before page content.
Use only supported syntax-highlighting language identifiers.
Write generic terminal output with the repository's plain-text language identifier.
Use lowercase language identifiers in code fences.
Use root-absolute paths for internal site links.
Do not use full production URLs for internal destinations.
Do not use unsupported relative page links.
Keep heading levels sequential and do not jump over a level.
Omit shell prompt symbols from copyable commands.
Write concise steps whose action, location, and expected result are unambiguous.
Keep reusable explanations in partials when multiple pages need the same maintained text.
Verify code examples against the documented API and current product behavior.
## Use the Site's Components and Images, and Change Redirects Only When Needed
Import MDX components only through the repository's central component barrel.
Consult component documentation for required properties and usage constraints.
Do not copy component internals into content when a supported public component exists.
Place new component code in the designated component directory.
Use the required custom-element prefix and kebab-case naming convention.
Keep each component in a directory named for that component.
Use PascalCase class names with the required suffix.
Do not rename exempt legacy elements merely to apply a newer prefix rule.
Keep source images in the optimized asset directory for their product or subject.
Verify image paths through a local full build.
Modify redirects only when a page move or URL migration requires them.
End redirect source paths with the required slash or accepted file or wildcard suffix.
Do not put fragments in redirect source URLs.
Detect redirect loops before review.
Run the dedicated redirect validator whenever the redirect file changes.
Keep component, image, link, and redirect changes within the page's intended scope.
## Run the Right Checks Locally and in CI Before Calling a Page Ready
Run schema and type checking after every content change.
Use a local full build to validate MDX parsing, image paths, and internal links.
Enable internal-link checking during the local full-validation build.
Do not run a known-to-time-out full build inside constrained CI.
In CI, run type checking, linting, and formatting checks as the reduced safe set.
For code changes, also run the repository's complete test suites.
Format every edited file before committing.
Run the repository's formatting check after automatic fixes.
Run redirect validation only when redirect configuration changed.
Run collection-type synchronization after schema or collection changes.
Match the local full-validation sequence to the CI pipeline when practical.
Expect CI to check file extensions, types, lint, formatting, build and links, redirects, and tests.
Treat style-scanner warnings as review evidence even when they are not hard failures.
Do not report a page ready while a directly relevant validation gate is missing.
Distinguish a CI environment limitation from an actual content failure.
Re-run directly affected checks after every corrective edit.
## Give Each Directory Entry an ID Made by the Site's Tool and Keep It
Give every directory-entry data file a unique stable identifier in the required first-line position.
Use the repository's exact identifier length and reduced-confusion character set.
For a six-character scheme, verify every generated value has exactly six characters.
Exclude visually ambiguous characters when the scheme requires it.
Generate identifiers randomly rather than deriving them from names.
Do not handcraft, guess, or copy an identifier.
Use the repository's identifier tool to check the complete collection.
Use its fix mode for missing, malformed, or duplicate identifiers.
Keep an existing valid identifier when the display name or filename changes.
Change an existing identifier only to repair a confirmed validation error.
Use the one required YAML extension consistently.
Treat identifier generation as an automated operation, not an editorial choice.
Check uniqueness across the whole directory collection.
Keep identifier generation and schema validation in CI.
Review the tool's diff before committing generated changes.
Do not manually adjust a generated identifier after the tool succeeds.
## Follow the Task Guides and Commit Rules When Sending Changes
Use the repository's contribution router before writing, editing, reviewing examples, adding changelogs, or preparing a pull request.
Follow the task-specific reference selected by that router.
Read a specialist bot's local instructions before changing its code, workflow routing, state, or deployment.
Keep tool-specific symlinks pointed at the committed shared agent configuration.
Load a repository skill only when its description matches the task.
Use the canonical style guide for prose and formatting decisions.
Use the component catalog for properties, examples, and mandatory patterns.
Use the procedure guide for step-by-step instructions.
Run tests in each runtime workspace affected by a code change.
Keep worker, server-runtime, and site-generator tests distinct.
Write commits in the repository's accepted product or type-prefixed form.
Make commit descriptions specific to the user-visible or technical correction.
Do not include unrelated formatting, generated content, or product changes.
Approve only when content, schemas, imports, assets, links, redirects, tests, and contribution conventions agree.