Libx Sample Documentation

Version Management

Learn how to manage multiple documentation versions—from defining a strategy to keeping older content online for reference.

Version Strategy

When to Create a New Version

Create a new documentation version when you hit any of these milestones:

  • Major API changes: Breaking changes that affect user implementations
  • Significant feature additions: New features that alter workflows
  • Platform upgrades: Framework or platform shifts that require new guidance
  • Audience changes: Different user groups that need tailored instruction

Version Lifecycle

Typical stages for each version:

  1. In development – Active work in progress
  2. Current/latest – Primary supported version
  3. Maintenance – Receives critical updates only
  4. Deprecated – No updates, shown for reference
  5. Archived – Removed from main navigation, accessible via direct links

Configuration

Version Definitions

Manage IDs, display names, release dates, and isLatest in apps/<project-name>/src/config/project.config.json. Example from sample-docs:

{
  "versioning": {
    "versions": [
      {
        "id": "v1",
        "name": "Version 1.0",
        "date": "2024-01-01T00:00:00.000Z",
        "isLatest": false
      },
      {
        "id": "v2",
        "name": "Version 2.0",
        "date": "2025-01-01T00:00:00.000Z",
        "isLatest": true
      }
    ]
  }
}

Instead of editing the file manually, run node scripts/create-version.js sample-docs v3 --interactive. The script creates backups, prompts for display names, copies an existing version, and prints a formatted diff of the config changes.

Directory Structure

Each version gets its own category tree under apps/<project-name>/src/content/docs/<version>/<lang>/:

apps/sample-docs/src/content/docs/
├── v1/ja/01-guide/...
└── v2/ja/
    ├── 01-guide/
    ├── 02-components/
    ├── 03-advanced/
    └── 04-reference/

Moving Between Versions

Evolving Content

When creating a new version:

  1. Review existing content: Decide what stays and what changes
  2. Document new features: Highlight additions and improvements
  3. Write migration guides: Explain differences between versions
  4. Keep legacy pages: Preserve older versions for reference

Migration Guide Example

---
title: "Migrating from v1 to v2"
description: "Changes required when moving from version 1.0 to 2.0"
---
# Migrating from v1 to v2

## Key Changes

### New Features
- Interactive components
- Advanced customization options
- Automation tooling

### Breaking Changes
- Simplified frontmatter
- Updated file structure
- New naming conventions

## Migration Steps

### 1. Update File Structure

Old:
    apps/sample-docs/src/content/docs/v1/ja/guide/basics.md
    apps/sample-docs/src/content/docs/v1/ja/components/sidebar.mdx

New:
    apps/sample-docs/src/content/docs/v2/ja/01-guide/01-basics.mdx
    apps/sample-docs/src/content/docs/v2/ja/02-components/04-sidebar-generation.mdx

### 2. Simplify Frontmatter

Old:
    ---
    title: "Basics"
    description: "Introductory usage"
    order: 1
    category: "guide"
    author: "Author Name"
    pubDate: 2024-01-01
    ---

New:
    ---
    title: "Basics"
    description: "Introductory usage"
    ---

Version Switching

User Experience

Help users move between versions:

  • Version selector: Provided in the shared header (it reads isLatest)
  • Consistent URLs: /docs/sample-docs/en/v1/01-guide/... versus /docs/sample-docs/en/v2/01-guide/...
  • Cross-version links: Point to related content in other versions when helpful

Automatic Redirects

Guide readers when appropriate:

// Redirect deprecated version traffic to the latest release
if (version === 'v0' && !user.preferences.showDeprecated) {
  redirect(`/docs/sample-docs/en/v2${currentPath}`);
}

Maintenance Strategy

Active Versions

For versions under support:

  • Regular updates with new information
  • Quick bug fixes and clarifications
  • Feedback loops with users
  • Performance and usability improvements

Legacy Versions

For older releases:

  • Critical fixes only (security, severe issues)
  • Clear deprecation notices
  • Plans for when to fully archive content

Automation Tools

Version Creation

  • node scripts/create-version.js sample-docs v3
    Updates project.config.json, copies the previous version into apps/sample-docs/src/content/docs/v3/<lang>/, and keeps structures aligned.
  • --interactive lets you pick display names, source versions, and the latest flag.
  • --no-copy creates empty directories so you can build a new structure from scratch.

Language Addition

  • node scripts/add-language.js sample-docs de --template-lang=ja
    Generates language folders, updates category translations, touches sites/landing/src/config/projects.config.json, stores backups in .backups/, and can optionally run build verification.

Document Creation

  • node scripts/create-document.js sample-docs en v2 --interactive
    Handles category selection, title input, and frontmatter generation via CLI prompts. After adjusting categories, run scripts/validate-category-structure.js to confirm translation keys.
  • pnpm build:sidebar
    Scans every app and generates apps/<project>/public/sidebar/sidebar-<lang>-<version>.json. Use pnpm build:sidebar-selective --projects=sample-docs for targeted regeneration.

Best Practices

Naming Versions

Use consistent names:

  • Semantic versions: v1.0, v1.1, v2.0
  • Clear identifiers: v2024, legacy, beta
  • Descriptive labels: modern, classic, next

Content Consistency

Align shared elements across versions:

  • Navigation: Keep similar structures when possible
  • Terminology: Use the same vocabulary
  • Style guide: Apply consistent tone and formatting

User Guidance

Help readers pick the right version:

## Version Selection Guide

### v2 (Recommended)
- Latest features and best practices
- Active support and updates
- Suggested for new projects

### v1 (Maintenance)
- Existing projects only
- Critical fixes only
- Plan to migrate to v2 soon

Troubleshooting

Common Issues

  • Broken links: Cross-version references not updated
  • Duplicate content: Versions fall out of sync
  • User confusion: Unclear guidance on which version to use

Solutions

  • Automated link checks: Validate URLs regularly
  • Diff tools: Track changes between versions
  • Clear messaging: Provide obvious guidance inside the docs

Next Steps

Once you understand version management: