documentation

The Diátaxis framework organizes documentation into four types: Tutorials (learning-oriented), How-to Guides (task-oriented), Reference (information-oriented), and Explanations (understanding-oriented). Each type serves a specific user need and requires distinct structure, tone, and content depth to create clear, maintainable documentation.

Yes. Astro Starlight supports MDX for building structured documentation with frontmatter metadata, code blocks with language tagging, and built-in components like callouts, tabs, and cards. This enables consistent formatting and rich content presentation across tutorials, guides, reference, and explanation pages.

Follow the Diátaxis how-to structure: start with a clear title and description in frontmatter, provide step-by-step instructions for accomplishing a specific task, use MDX-compatible code blocks with language tags, and apply callout components for notes and tips. Minimize narrative prose and focus on actionable content.

Yes. Frontmatter is mandatory in Astro Starlight and must include at minimum a title and description. This metadata enables proper page organization, navigation, and content discovery while maintaining consistency across your documentation site.

Apply style guidelines that separate concerns: keep Reference entries concise and factual, reserve Explanations for conceptual depth, and use code samples strategically. Diátaxis framework principles help prevent redundancy by assigning each content type a single, focused purpose.

Astro Starlight includes callout components for notes, tips, and cautions, code blocks with syntax highlighting and language identification, tabs for tabbed content, and cards for structured layouts. These MDX components ensure consistent formatting and improve readability across documentation.