MkDocs Documentation Template

A user-friendly template for publishing Markdown documentation to GitHub Pages using MkDocs with the Material theme.

🚀 Quick Start

Option 1: Deploy to GitHub Pages (No local setup required)

1. Enable GitHub Pages:

   • Go to repository Settings → Pages
   • Set Source to GitHub Actions

2. Push to main branch:

   git add .
   git commit -m "Initial documentation"
   git push origin main

3. View your site at: https://softwareworkercom.github.io/docs/

Option 2: Local Development

1. Install dependencies:

   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt

2. Start local server:

   mkdocs serve

3. Open http://127.0.0.1:8000 in your browser

📁 Project Structure

docs/
├── .github/
│   └── workflows/
│       └── deploy.yml      # GitHub Actions workflow
├── docs/                   # Documentation content
│   ├── index.md           # Home page
│   ├── getting-started/   # Getting started guides
│   ├── user-guide/        # User documentation
│   └── contributing.md    # Contribution guidelines
├── mkdocs.yml             # MkDocs configuration
├── requirements.txt       # Python dependencies
└── README.md              # This file

✨ Features

• Material Design theme with dark/light mode toggle
• Automatic deployment via GitHub Actions
• Full-text search for all documentation
• Code highlighting with copy button
• Responsive design for mobile devices
• Edit on GitHub links for easy contributions

📝 Writing Documentation

Add new pages by:

1. Creating a .md file in the docs/ folder
2. Adding it to the nav section in mkdocs.yml

See the Writing Content guide for Markdown tips.

⚙️ Configuration

Edit mkdocs.yml to customize:

• Site name and description
• Color scheme
• Navigation structure
• Enabled features

📚 Documentation

Visit the documentation site for detailed guides:

• Quick Start Guide
• Installation Guide
• Configuration Guide

📄 License

This project is open source and available under the MIT License.