Documentation Fundamentals

Welcome to the comprehensive documentation guide! This section teaches you everything you need to create, edit, and manage documentation effectively.

What You’ll Learn

In this comprehensive guide you’ll discover:

Document Creation: How to create new documents with the proper structure
Content Organization: Best practices for organizing and categorizing content
Component Usage: How to use built-in UI components to enhance your documentation
Advanced Features: Automation, customization, and deployment strategies

Documentation Philosophy

Good documentation should be:

Clear and Concise: Easy to understand and follow
Well-Organized: Logical structure and navigation
Comprehensive: Covers all necessary topics
Maintainable: Easy to update and keep current
Accessible: Available to all users regardless of ability

Getting Started Checklist

Before you begin creating documentation, ensure you have:

Development Environment: Node.js 18+, pnpm, and a code editor
Project Understanding: Familiarity with the project structure
Content Plan: Clear idea of what you want to document
Audience Awareness: Understanding of who will read your documentation

Project Structure Overview

sample-docs is managed as one application inside the libx monorepo. The directories you’ll edit most often live here:

apps/sample-docs/
├── astro.config.mjs                 # Project-level Astro configuration
├── src/
│   ├── config/project.config.json   # Version, language, and category translations
│   ├── content/docs/
│   │   ├── v1/en/01-guide/...
│   │   └── v2/en/<category>/<page>.mdx
│   └── env.d.ts, etc.
├── public/sidebar/                  # Navigation JSON generated by build:sidebar
└── package.json                     # Used with `pnpm --filter=sample-docs ...`

Shared packages (packages/ui, packages/content-utils, and others) live at the repo root, so the app can reuse UI and utilities without owning its own src/lib.

Frequently Used Commands

After pnpm install, the fastest way to work on sample-docs alone is to run the following from the repo root:

# Start the dev server for this project only
pnpm --filter=sample-docs dev

# Regenerate the sidebar after changing the doc structure
pnpm build:sidebar

# Build only sample-docs
pnpm build:selective --projects=sample-docs

Key Features

The documentation system automatically generates sidebar navigation based on your content structure and frontmatter configuration.

Multi-language Support

Content can be created in multiple languages with automatic language switching and URL management.

Component Integration

You can call Icon, Tabs, Alert, and other components from the @docs/ui package directly within MDX.

Version Management

Combine apps/sample-docs/src/config/project.config.json with scripts/create-version.js to safely maintain multiple documentation versions.

Content Creation Workflow

The typical workflow for creating documentation involves:

Planning: Define the scope and structure of your content
Creating: Write the initial content using Markdown and MDX
Enhancing: Add components, examples, and interactive elements
Organizing: Set up proper categories and navigation
Testing: Verify links, formatting, and functionality
Publishing: Deploy and make available to users

Writing Guidelines

When creating documentation:

Start with the user’s goal: What are they trying to accomplish?
Use clear headings: Create a logical hierarchy of information
Include examples: Show, don’t just tell
Be consistent: Use the same terminology and formatting throughout
Test everything: Verify that instructions actually work

Next Steps

Ready to start creating documentation? The next guides walk you through:

Creating Documents: Learn to create new documentation files
Editing Documents: Master the editing process and best practices
Organizing Content: Structure your content for maximum usability
Version Management: Handle multiple versions effectively

Let’s start your documentation journey!