Skip to main content

MkDocs Quick Start

Quick reference for working with MkDocs documentation.

Installation​

# Install MkDocs and Material theme
pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin

# Or install from requirements file
pip install -r requirements-docs.txt

Local Development​

# Serve documentation locally
mkdocs serve

# Open http://127.0.0.1:8000 in your browser

Building​

# Build static site
mkdocs build

# Output will be in the `site/` directory

Adding New Pages​

  1. Create markdown file in docs/ directory
  2. Add to navigation in mkdocs.yml: 
    nav:
      - Your Section:
        - your-section/page.md
  3. Test locally: mkdocs serve
  4. Commit and push - GitHub Actions will deploy automatically

Configuration​

Edit mkdocs.yml to customize:

  • Site name and description
  • Theme colors and features
  • Navigation structure
  • Plugins

Deployment​

Deployment is automatic via GitHub Actions:

  • Push to main branch
  • Workflow triggers unified Documentation repo to update and deploy
  • Site available at https://your-username.github.io/FishingLog.Backend/

Useful Commands​

# Validate configuration
mkdocs build --strict

# Serve with auto-reload
mkdocs serve --dev-addr=127.0.0.1:8000

# Build for production
mkdocs build --clean

Resources​