Organizing Content

Effective organization helps readers navigate intuitively and find the information they need quickly.

Content Hierarchy

Directory Structure

Keep a clear hierarchy for every project:

apps/sample-docs/src/content/docs/[version]/[lang]/
├── 01-guide/           # Getting started and tutorials
│   ├── 01-getting-started.mdx
│   ├── 02-creating-documents.mdx
│   └── 03-editing-documents.mdx
├── 02-components/      # UI components and examples
│   ├── 01-overview.mdx
│   ├── 02-icons.mdx
│   └── 03-tabs.mdx
├── 03-advanced/        # Advanced topics
│   ├── 01-customization.mdx
│   └── 02-automation.mdx
└── 04-reference/       # Reference materials
    └── 01-frontmatter.mdx

Numbering Conventions

Use numeric prefixes to enforce order:

• Categories: 01-guide/, 02-components/, 03-advanced/
• Documents: 01-getting-started.mdx, 02-creating-documents.mdx

This keeps the sequence consistent regardless of file-system sorting.

Category Design

Purpose-Based Categories

Align sections with user intent:

Progressive Learning Path

Structure content around the user journey:

1. Guide — foundational concepts and first steps
   ↓
2. Practical — day-to-day tasks and workflows
   ↓
3. Advanced — customization and optimization
   ↓
4. Reference — detailed lookup information

Document Structure

Information Hierarchy

Use a predictable flow inside each page:

# Title
Overview and what readers will learn

## Key Concepts
Foundational understanding

## Basic Usage
Practical example

## Advanced Usage
More complex scenarios

## Best Practices
Recommendations

## Next Steps
Links to related content

Heading Levels

• H1 (#): Page title only
• H2 (##): Main sections
• H3 (###): Subsections
• H4+: Use only when truly necessary

Cross-References

Strategic Linking

Connect related content deliberately:

<!-- Concept to implementation -->
Once you understand the basics, try the [hands-on example](/v2/en/01-guide/02-creating-documents).

<!-- Deep dives -->
For additional details, see the [frontmatter reference](/v2/en/04-reference/01-frontmatter).

<!-- Guided progression -->
Next, continue with [advanced customization](/v2/en/03-advanced/01-customization).

Link Patterns

Use descriptive text for every link:

<!-- Preferred -->
[Creating Documents](/v2/en/01-guide/02-creating-documents)
[Component Overview](/v2/en/02-components/01-overview)

<!-- Avoid -->
[Click here](/v2/en/01-guide/02-creating-documents)
[More info](/v2/en/02-components/01-overview)

Navigation Design

Automatic Navigation

Let automation handle the basics:

• Sidebar: Generated from the directory structure
• Previous/Next links: Derived from file naming
• Breadcrumbs: Calculated from the hierarchy

Custom Navigation

Add explicit links when necessary:

## Related Topics

Pair this section with:

- [Basic Setup](/v2/en/01-guide/01-getting-started)
- [Using Components](/v2/en/02-components/01-overview)
- [Deployment Guide](/v2/en/03-advanced/03-deployment)

Content Guidelines

Maintain Consistency

• Terminology: Use the same term for the same concept
• Formatting: Apply shared patterns for code, lists, and emphasis
• Tone: Maintain a consistent voice
• Structure: Mirror layouts for similar topics

Avoid Duplication

• Let one document own each concept and link to it elsewhere
• Provide short summaries instead of repeating entire sections
• When duplication is unavoidable, highlight the authoritative source

Strategies by Content Type

Tutorials

Provide a guided learning experience:

---
title: "Creating Your First Document"
description: "A complete guide to building a document from scratch"
---

# Creating Your First Document

In this tutorial you'll create a complete document from start to finish.

## What You'll Learn

After finishing you'll be able to:
- Create new document files
- Add the proper frontmatter
- Write effective content

## Prerequisites

- Basic Markdown knowledge
- Project development environment set up

## Step 1: Create the File
[Detailed instructions...]

Reference Material

Structure references for quick lookups:

---
title: "Configuration Options"
description: "Complete reference of all available configuration options"
---

# Configuration Options

## Basic Settings

### title
- **Type**: string
- **Required**: Yes
- **Description**: Document title
- **Example**: `"My Guide"`

### description
- **Type**: string
- **Required**: Yes
- **Description**: Brief explanation of the document
- **Example**: `"This guide explains basic usage."`

Quality Assurance

Organization Checklist

• Logical placement: Content lives in the right category
• Consistent naming: Matches existing patterns
• Clear ordering: Fits the reading flow
• No duplication: Avoids repeating other docs
• Updated links: Connects to related guides

Regular Review

Revisit the structure on a cadence:

1. Analyze usage: Which paths are most popular?
2. Find gaps: Where are connections missing?
3. Consider reorganization: Would a new category help?
4. Collect feedback: Incorporate suggestions from readers

Next Steps

After mastering content organization:

• Version Management: Keep multiple versions in sync
• Component Overview: Use UI components to enhance docs
• Automation: Explore scripts that keep structures consistent