goplt/docs/MKDOCS_README.md

MkDocs Setup

This project uses MkDocs with the Material theme for documentation.

All documentation tooling files are self-contained in the docs/ directory.

Prerequisites

You can run MkDocs in two ways:

Option 1: Local Python Installation

• Python 3.8 or higher
• pip (Python package manager)

Option 2: Docker (Recommended - No Python installation needed)

• Docker and Docker Compose

Installation

1. Install the required Python packages:

cd docs
pip install -r requirements.txt

Or if you prefer using a virtual environment:

cd docs
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Usage

You can use either the Makefile commands from the project root (recommended) or run MkDocs directly from the docs/ directory.

Using Makefile (Recommended)

From the project root, use the Makefile commands:

# Using Docker (easiest, no Python needed)
make docs-docker-compose-up
# or
make docs-docker

# Using local Python
make docs-install    # Install dependencies
make docs-serve      # Serve documentation
make docs-build    # Build static site
make docs-deploy    # Deploy to GitHub Pages

# Show all available commands
make help

The documentation will be available at http://127.0.0.1:8000 with live reload enabled.

Using Docker Directly

From the docs/ directory:

cd docs

# Using docker-compose (easiest)
docker-compose up --build

# Using Docker directly
docker build -t goplt-docs:latest .
docker run --rm -it -p 8000:8000 -v "$(pwd):/docs:ro" goplt-docs:latest

# Build static site
docker run --rm -v "$(pwd):/docs:ro" -v "$(pwd)/site:/docs/site" goplt-docs:latest mkdocs build

Using MkDocs Directly

From the docs/ directory:

cd docs

# Serve documentation locally with auto-reload
mkdocs serve

# Build static site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

Configuration

The main configuration file is docs/mkdocs.yml. Key settings:

• Site name and metadata: Configured at the top
• Theme: Material theme with light/dark mode support
• Navigation: Defined in the nav section
• Plugins: Search and git revision date plugins enabled
• Markdown extensions: Various extensions for code highlighting, tables, etc.
• docs_dir: Set to "content" - markdown files are in the content/ subdirectory

Project Structure

goplt/
├── docs/                    # Documentation directory (self-contained)
│   ├── mkdocs.yml          # MkDocs configuration
│   ├── requirements.txt    # Python dependencies
│   ├── Dockerfile          # Docker image for MkDocs
│   ├── docker-compose.yml  # Docker Compose configuration
│   ├── .dockerignore       # Docker ignore patterns
│   ├── MKDOCS_README.md    # This file
│   ├── content/           # Documentation content (markdown files)
│   │   ├── index.md       # Home page
│   │   ├── requirements.md # Requirements document
│   │   ├── plan.md        # Implementation plan
│   │   ├── playbook.md    # Implementation playbook
│   │   ├── adr/           # Architecture Decision Records
│   │   └── stories/       # Implementation tasks
│   └── site/              # Generated site (gitignored)
└── Makefile               # Makefile with docs commands (runs from root)

Adding New Documentation

1. Add markdown files to the docs/content/ directory
2. Update docs/mkdocs.yml to add entries to the nav section
3. Run make docs-serve or make docs-docker from project root to preview changes

Customization

Theme Colors

Edit the theme.palette section in docs/mkdocs.yml to change colors.

Navigation

Update the nav section in docs/mkdocs.yml to reorganize or add new pages.

Plugins

Add or remove plugins in the plugins section of docs/mkdocs.yml.

Troubleshooting

• Import errors: Make sure all dependencies are installed: cd docs && pip install -r requirements.txt
• Navigation issues: Check that file paths in docs/mkdocs.yml match actual file locations
• Build errors: Run mkdocs build --verbose from the docs/ directory for detailed error messages
• Docker issues: Make sure Docker is running and you have permissions to run containers

Benefits of Self-Contained Docs

• All documentation tooling is in one place
• Easy to share or move the docs directory
• Doesn't pollute the project root
• Can be versioned or deployed independently