# Authoring Content

This section teaches you everything about writing documentation in MarkStack. You will learn how to organize content, use frontmatter for metadata, leverage markdown extensions for rich formatting, and follow best practices that make your documentation clear and maintainable.

MarkStack extends standard markdown with GitHub-style features like callout alerts, task lists, footnotes, and syntax-highlighted code blocks. Understanding these features helps you create documentation that communicates effectively and looks professional.

# What This Section Covers

# Content Model

The Content Model guide explains how MarkStack organizes documentation:

• How folders become navigation categories
• How markdown files become documentation pages
• The role of _index.md files for category landing pages
• How titles transform into URL slugs
• Strategies for organizing large documentation projects
• How nesting and ordering work

Understanding the content model is essential. It determines how your documentation appears in the sidebar, how URLs generate, and how readers navigate your site.

# Frontmatter

The Frontmatter guide covers the YAML metadata at the top of each markdown file:

• The title field and how it affects navigation, page titles, and URLs
• The description field and its role in search results and SEO
• How frontmatter interacts with siteconfig.json defaults
• Best practices for writing effective titles and descriptions

Good frontmatter makes your documentation discoverable in search engines and helps readers understand what each page contains before clicking.

# Markdown Features

The Markdown Features guide documents everything you can do with markdown in MarkStack:

• Standard markdown syntax (headings, paragraphs, lists, links, images)
• GitHub-style callout alerts (NOTE, TIP, IMPORTANT, WARNING, CAUTION)
• Fenced code blocks with syntax highlighting for 190+ languages
• Task lists with checkboxes
• Footnotes for references and citations
• Tables for structured data
• Horizontal rules and other formatting

Each feature includes examples you can copy directly into your documentation.

# Media and Links

The Media and Links guide covers how to include assets and create connections:

• Where to place images and how to reference them
• Handling downloadable files like PDFs
• Internal linking between documentation pages
• External links to other websites
• Accessibility best practices for images and links

Proper linking ensures your documentation works correctly after deployment and provides a good experience for all readers.

# Examples

The Examples page provides ready-to-use templates:

• Category landing pages with navigation
• Standard documentation pages with frontmatter
• Pages using multiple markdown features together
• Common patterns you can adapt for your needs

These examples help you start new pages quickly without recreating boilerplate.

# Recommended Reading Order

If you are new to writing documentation in MarkStack, read these guides in order:

1. Content Model first, to understand how organization works
2. Frontmatter second, to learn about metadata
3. Markdown Features third, for formatting options
4. Media and Links fourth, for asset handling
5. Examples as needed, when creating new content

If you already know markdown basics, you can skip to specific guides for the information you need.

# Quick Tips for Good Documentation

As you work through this section, keep these principles in mind:

TIP As you read through this section, have a markdown file open in your editor. Try each feature as you learn about it. The immediate feedback helps concepts stick.