Mining/MKDOCS_SETUP.md

MkDocs Setup Guide

This document provides a quick reference for the MkDocs documentation setup.

Quick Start

# Install dependencies
pip install -r docs/requirements.txt

# Serve locally (with live reload)
mkdocs serve

# Build static site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

Configuration Summary

Location

• Config file: mkdocs.yml
• Docs directory: docs/
• Build output: site/

Theme Settings

• Theme: Material for MkDocs
• Default mode: Dark mode (with toggle)
• Primary color: Deep Purple
• Accent color: Purple
• Font: Roboto / Roboto Mono

Key Features Enabled

• Navigation tabs (sticky)
• Instant navigation with prefetch
• Search with suggestions
• Table of contents integration
• Code copy buttons
• Code annotations
• Edit/view page actions
• Git revision dates

Plugins Configured

1. search: Enhanced search with smart separators
2. git-revision-date-localized: Shows page creation/modification dates
3. minify: Minifies HTML for production
4. glightbox: Image lightbox with zoom

Markdown Extensions

• Admonitions (notes, warnings, tips)
• Code highlighting with line numbers
• Tabbed content blocks
• Task lists
• Mermaid diagrams
• Emojis
• Math equations (MathJax)
• Custom fences
• And more...

Documentation Structure

docs/
├── index.md                    # Home page
├── getting-started/            # Installation, quickstart, config
├── cli/                        # CLI command reference
├── api/                        # API documentation
├── dashboard/                  # Web dashboard docs
├── desktop/                    # Desktop app docs
├── development/                # Development guides
├── architecture/               # Architecture docs
├── pools/                      # Pool integration
├── miners/                     # Miner-specific docs
├── troubleshooting/            # Troubleshooting guides
├── stylesheets/
│   └── extra.css              # Custom styles
├── requirements.txt           # Python dependencies
└── README.md                  # Docs contributor guide

Deployment

Automatic (GitHub Actions)

Documentation is automatically built and deployed to GitHub Pages on every push to main that modifies:

• docs/**
• mkdocs.yml
• .github/workflows/docs.yml

Workflow: .github/workflows/docs.yml

Manual Deployment

# Build and deploy to gh-pages branch
mkdocs gh-deploy --force

Viewing Documentation

Local Development

• URL: http://127.0.0.1:8000/
• Command: mkdocs serve

Production

• URL: https://snider.github.io/Mining/
• Branch: gh-pages (auto-generated)

Adding New Pages

1. Create markdown file in appropriate directory:

   # Example: Add new CLI command documentation
   touch docs/cli/benchmark.md
   

2. Add to navigation in mkdocs.yml:

   nav:
     - CLI Reference:
       - benchmark: cli/benchmark.md
   

3. Test locally:

   mkdocs serve
   

4. Commit and push (auto-deploys)

Markdown Features

Code Blocks with Highlighting

```go title="main.go" linenums="1" hl_lines="2 3"
package main

import "fmt"

func main() {
    fmt.Println("Hello!")
}
```

Admonitions

!!! note "Note Title"
    This is a note admonition.

!!! warning "Warning"
    This is a warning.

!!! tip "Pro Tip"
    This is a helpful tip.

Tabbed Content

=== "Linux"
    ```bash
    ./miner-ctrl serve
    ```

=== "Windows"
    ```powershell
    miner-ctrl.exe serve
    ```

Mermaid Diagrams

```mermaid
graph LR
    A[Start] --> B{Check}
    B -->|Yes| C[OK]
    B -->|No| D[Error]
```

Troubleshooting

Site not building?

# Check for errors
mkdocs build --strict --verbose

Missing dependencies?

# Reinstall all dependencies
pip install -r docs/requirements.txt --force-reinstall

Navigation not showing up?

• Check YAML syntax in mkdocs.yml nav section
• Ensure markdown files exist at specified paths
• Verify indentation (use spaces, not tabs)

Changes not appearing locally?

• MkDocs has live reload, but try:
  • Hard refresh browser (Ctrl+Shift+R)
  • Restart mkdocs serve
  • Clear browser cache

Resources

• MkDocs Documentation
• Material for MkDocs
• PyMdown Extensions
• Mermaid Diagrams