Organizing Content

Effective content organization is crucial for creating documentation that users can navigate intuitively and find information quickly.

Content Hierarchy

Directory Structure

Organize content using a clear hierarchy:

src/content/docs/[lang]/[version]/
├── 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
    └── 02-configuration.mdx

Numbering Convention

Use numbered prefixes to control order:

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

This ensures consistent ordering regardless of file system behavior.

Category Design

Purpose-Based Categories

Organize by user intent and workflow:

User Journey Mapping

Structure content to match common user journeys:

User Journey: New User → Basic User → Power User
     ↓              ↓              ↓
   Guide      →  Components  →  Advanced

Sidebar Configuration

Automatic Generation

The system automatically generates sidebars based on:

1. Directory structure: Categories from folder names
2. Frontmatter: Custom categories and ordering
3. Category translations: Localized category names

Frontmatter Control

Control sidebar appearance with frontmatter:

---
title: "Document Title"
category: "guide"           # Override default category
categoryOrder: 1            # Category position in sidebar
order: 2                   # Document position within category
---

Category Translations

Define category names in project.config.ts:

categoryTranslations: {
  en: {
    guide: 'Guide',
    components: 'Components',
    advanced: 'Advanced',
    reference: 'Reference'
  },
  ja: {
    guide: 'ガイド',
    components: 'コンポーネント',
    advanced: '高度な設定',
    reference: 'リファレンス'
  }
}

Content Types and Patterns

Tutorial Content

Structure: Problem → Solution → Practice

# Creating Your First Document

## What You'll Build

By the end of this tutorial, you'll have created a complete documentation page with navigation and components.

## Prerequisites

- Basic understanding of Markdown
- Text editor or IDE

## Step 1: Create the File

First, create a new file in the correct location...

## Step 2: Add Frontmatter

Next, add the required metadata...

## What You've Learned

You now know how to create documentation files with proper structure and metadata.

## Next Steps

- Try adding components to your document
- Explore different content categories

Reference Content

Structure: Overview → Details → Examples

# Frontmatter Reference

## Overview

Frontmatter is YAML metadata that controls document behavior and appearance.

## Required Fields

### title
- **Type:** string
- **Description:** Document title displayed in navigation and page header
- **Example:** `title: "Getting Started"`

### description
- **Type:** string  
- **Description:** Brief description for SEO and previews
- **Example:** `description: "Learn the basics of documentation"`

## Optional Fields

[Detailed field descriptions...]

## Examples

### Basic Document
```yaml
---
title: "My Document"
description: "Document description"
---

Advanced Configuration

---
title: "Advanced Guide"
description: "Advanced configuration options"
category: "advanced"
order: 1
---

### How-To Content

**Structure:** Goal → Steps → Validation

```markdown
# How to Add Navigation Links

## Goal

Add previous and next navigation links to create a logical reading flow.

## Steps

### 1. Identify Adjacent Documents

Determine which documents should come before and after in the reading sequence.

### 2. Add Frontmatter Links

Update the frontmatter with navigation links:

```yaml
prev:
  text: "Previous Document"
  link: "/en/v2/guide/previous"
next:
  text: "Next Document"  
  link: "/en/v2/guide/next"

3. Test Navigation

Preview your changes and verify the navigation links work correctly.

Verification

Your document should now show:

• Previous link in the bottom-left
• Next link in the bottom-right
• Breadcrumb navigation at the top

## Information Architecture

### Progressive Disclosure

Layer information from general to specific:

1. **Overview**: High-level concepts and benefits
2. **Getting Started**: Basic implementation
3. **Detailed Guides**: Comprehensive coverage
4. **Advanced Topics**: Expert-level content
5. **Reference**: Quick lookup information

### Cross-Referencing

Create connections between related content:

```markdown
<!-- In a guide document -->
For more details about component properties, see the 
[Components Reference](/en/v2/reference/components).

<!-- In a component document -->
This component is commonly used in tutorials. See 
[Creating Interactive Docs](/en/v2/guide/interactive-content).

<!-- In advanced topics -->
Before proceeding, ensure you understand the basics covered in 
[Getting Started](/en/v2/guide/getting-started).

Navigation Patterns

Linear Navigation

For tutorial sequences, use clear previous/next links:

# Document 1
next:
  text: "Installation"
  link: "/en/v2/guide/installation"

# Document 2  
prev:
  text: "Getting Started"
  link: "/en/v2/guide/getting-started"
next:
  text: "Configuration"
  link: "/en/v2/guide/configuration"

Hub-and-Spoke Navigation

For reference sections, link back to overview pages:

# Component Details

[← Back to Components Overview](/en/v2/components/overview)

## Icon Component

Detailed information about the Icon component...

### Related Components

- [Button Component](/en/v2/components/button)
- [Navigation Component](/en/v2/components/navigation)

Content Maintenance

Regular Review

Establish a review schedule:

• Monthly: Check for broken links and outdated information
• Quarterly: Review content organization and user feedback
• Annually: Major structural reorganization if needed

Analytics and Feedback

Track content usage:

• Most visited pages: Ensure they’re well-organized and current
• High exit pages: May need better navigation or content
• Search terms: Identify content gaps or organization issues

Continuous Improvement

• Gather user feedback: What’s confusing or hard to find?
• Monitor support questions: Common questions indicate content gaps
• Test with new users: Fresh perspective on organization effectiveness

Best Practices Summary

1. Start with user goals: Organize around what users want to accomplish
2. Use consistent patterns: Apply the same structure across similar content
3. Provide multiple paths: Support different learning styles and needs
4. Test navigation: Ensure users can find information intuitively
5. Keep it simple: Avoid over-categorization or complex hierarchies
6. Plan for growth: Structure should accommodate new content easily

Next Steps

Now that you understand content organization:

• Version Management: Learn how to handle multiple documentation versions
• Component Overview: Explore available UI components
• Advanced Customization: Customize the documentation system for your needs