Documentation Versioning Overview

Welcome to the sample documentation project! This page explains the versioning structure used inside the libx monorepo and shows how versions like v1 and v2 coexist.

Versioning in libx

Each application stores documentation under apps/<project-name>/src/content/docs/<version>/<lang>/. The UI is generated from project.config.json, which describes versions and languages.

Sample structure for sample-docs:

apps/sample-docs/
├── src/
│   ├── config/project.config.json   # Centralized version/language definitions
│   └── content/docs/
│       ├── v1/
│       │   └── ja/01-guide/...
│       └── v2/
│           ├── ja/
│           └── en/
└── public/sidebar/                  # Auto-generated sidebar JSON

The versioning.versions section in project.config.json controls IDs, names, release dates, and which version is marked as latest. Running node scripts/create-version.js sample-docs v3 generates every language/category structure automatically when you need a new version.

Why Keep v1 and v2?

• Visible migration plans: Maintain v1 while building v2 so users can migrate gradually.
• Stable URLs: /docs/sample-docs/en/v1/... and /docs/sample-docs/en/v2/... stay distinct, which helps both readers and search engines.
• Translation control: Track translation progress per version, leverage rollback features in scripts/add-language.js, and restore content from .backups/.

Version 1 (this page)

• Goal: Provide a quick overview of the versioning model
• Contents: Directory layout, config files, core commands
• Audience: Anyone new to the libx documentation layout

Version 2 (main docs)

• Goal: Deliver end-to-end guidance on creating, editing, and automating docs
• Contents: Guides, components, advanced topics, references
• Audience: Editors actively working on sample-docs

Languages and Sidebar

sample-docs uses locale-first URLs (/docs/sample-docs/<lang>/<version>/...). Passing pathPattern: 'locale-first' to getSidebarAsync from @docs/content-utils generates per-language, per-version sidebar JSON (for example apps/sample-docs/public/sidebar/sidebar-en-v2.json).

Operating the Versioning System

1. Parallel updates without structural drift: Copy the v1 category structure to v2, then extend v2 as needed.
2. Edit configs safely: Prefer scripts such as scripts/create-version.js or scripts/add-language.js so changes are backed up automatically.
3. Regenerate navigation: Run pnpm build:sidebar after adding versions or categories, then confirm behavior with pnpm dev --filter=sample-docs.

Next Steps

The latest v2 guides cover the hands-on workflows:

• Documentation Fundamentals – Review core principles shared across apps
• Creating Documents – Learn the creation script workflow
• Version Management – Understand how project.config.json and automation work together

Continue to the next page to see these practices in action.