164 lines
4.6 KiB
Markdown
164 lines
4.6 KiB
Markdown
# 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
|
|
|