Astro Versioned Documentation System

A foundational guide to understanding and setting up the versioned documentation hub using Astro.

Table of Contents

Overview

This documentation system provides:

  • Automatic versioning: Support for multiple versions of the same document
  • Smart discovery: Automatically finds and organizes markdown files
  • Category organization: Directory structure becomes navigation structure
  • Responsive design: Mobile-friendly interface with Tailwind CSS
  • Zero configuration: Drop markdown files and they’re automatically processed

Key Features

  • 📁 File-based routing - Documents are automatically discovered
  • 🔄 Version management - Support for document_v1.md, document_v2.md naming
  • 🏗️ Category support - Organize docs in subdirectories
  • 🎨 Customizable themes - Built with Tailwind CSS
  • ⚡ Performance optimized - Caching and efficient file scanning
  • 📱 Mobile responsive - Works great on all device sizes

Quick Start

1. Fork and Clone

git clone https://github.com/yourusername/astro-docs-system.git
cd astro-docs-system
npm install

2. Add Your First Document

Create a file at /src/pages/docs/getting-started.md:

# Getting Started

Welcome to your documentation system!

This is your first document.

3. Start Development Server

npm run dev

Visit http://localhost:4321/docs to see your documentation.

Architecture

Core Components

  1. Preprocessing Script (scripts/preprocess-markdown.js)

    • Runs before dev/build
    • Automatically adds layout frontmatter to markdown files
    • Calculates correct relative paths

  2. Document Utilities (src/utils/docUtils.ts)

    • Scans and discovers all documentation files
    • Parses version information from filenames
    • Provides caching for performance
    • Groups documents by category and version

  3. Layout System

    • MarkdownLayout.astro - Wrapper for individual docs
    • DocsLayout.astro - Base layout with navigation
    • MarkdownNav.astro - Version switcher and breadcrumbs

  4. Index Page (src/pages/docs/index.astro)

    • Overview of all available documentation
    • Category organization
    • Version selection interface

File Processing Flow

1. Developer adds .md file to /src/pages/docs/
2. preprocess-markdown.js runs (dev/build)
3. Script adds layout frontmatter automatically
4. Astro builds page using MarkdownLayout
5. docUtils.ts scans and categorizes all docs
6. Navigation components show versions/related docs

File Organization

Naming Conventions

Single Documents

/src/pages/docs/
├── installation.md          # Latest version
├── installation_v1.md       # Version 1
├── installation_v2.md       # Version 2
└── configuration.md         # Latest version

Categorized Documents

/src/pages/docs/
├── api/
│   ├── authentication.md    # Latest
│   ├── authentication_v1.md # Version 1
│   └── endpoints.md         # Latest
├── guides/
│   ├── deployment.md        # Latest
│   └── troubleshooting.md   # Latest
└── reference/
    └── cli-commands.md      # Latest

Version Resolution

The system intelligently resolves document versions:

  • Latest Version: Files without _vX suffix (e.g., guide.md)
  • Specific Versions: Files with _vX suffix (e.g., guide_v1.md, guide_v2.md)
  • URL Mapping:
    • /docs/guide → serves latest version
    • /docs/guide_v1 → serves version 1 specifically

Category Structure

Directory structure automatically becomes navigation:

docs/api/authentication.md → Docs → API → Authentication
docs/guides/deployment.md  → Docs → Guides → Deployment
docs/configuration.md      → Docs → Configuration

This documentation system provides the foundation for a versioned documentation hub. The architecture is designed to be extended with additional features, customizations, and integrations as needed.