# MkDocs Setup

This project uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) 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:

```bash
cd docs
pip install -r requirements.txt
```

Or if you prefer using a virtual environment:

```bash
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:

```bash
# 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:

```bash
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:

```bash
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