Guideline page template

Use this structure for new and existing MDS guideline-page drafts. Keep policy sections only when the approved source supports them. Do not invent sections...

Use this structure for new and existing MDS guideline-page drafts. Keep policy sections only when the approved source supports them. Do not invent sections to fill the skeleton.

Frontmatter

title and description are required MDX fields. synopsis improves retrieval but must not copy the description. Use hideRelatedPages only when the page provides its own related-guidance section.

The writer workflow adds draft-only frontmatter when required.

Structure

  1. Open with the policy’s purpose and boundary.
  2. Use policy-first ## sections ordered by the decisions a reader must make.
  3. Use imperative ### headings for specific actions or choices.
  4. State each rule before its rationale and conditions.
  5. Use examples only when visual or contextual comparison communicates the policy better than prose.
  6. End with related guidance only when the links clarify ownership or a decision boundary.

Anchors

Preserve an existing heading when inbound links depend on its generated anchor and the heading still describes the policy accurately. When accuracy requires a heading change, record the old anchor, new anchor, and every inbound link that must change during promotion.

Do not edit inbound files from the draft workflow.