Vaulthalla Logo

Formatting Reference

Markdown formatting expectations for synced docs packages.

Formatting Reference

Docs are plain .md files that pass through @valkyrianlabs/payload-markdown. Keep them readable in Git first; the renderer can enhance supported directives without turning the source into MDX.

Expected Shape

Each page should have:

  • supported frontmatter
  • one H1 that matches the page topic
  • short sections with H2 and H3 headings
  • root-relative internal links
  • supported payload-markdown directives only when they add clarity
1---2title: Quick Start3navTitle: Quick Start4description: Run the default docs workflow.5order: 206status: published7tags:8  - getting-started9---10 11# Quick Start12 13Introductory paragraph.14 15## Validate Local Docs16 17Run the validator before syncing.

Use root-relative docs links inside the docs set:

1[Publishing](/workflow/publishing)

Do not use relative links for internal docs pages:

../workflow/publishing.md

Do not hardcode production docs domains for internal navigation.

Directives

Supported directives are:

  • :::toc
  • :::callout
  • :::details
  • :::steps
  • :::cards
  • :::card

Keep blank lines around nested directive content. Do not invent directive names, props, layout modes, or MDX components.

What Not To Add

  • .mdx files
  • arbitrary YAML frontmatter objects
  • inline frontmatter arrays such as tags: [api, sync]
  • HTML scripts, iframes, or client-side widgets
  • one Payload Page per Markdown file
  • hidden docs files as a substitute for clean navigation metadata
  • links to generated Payload Admin records as if they were public docs routes

Agent Skills

Agent skill files are not human docs pages. Keep them under /skills or in the project-local agent install directory, and keep /docs focused on rendered Markdown documentation.