MkDocs Deployment Guide¶

This guide covers deploying the AzharStore documentation using MkDocs.

Local Development¶

Installation¶

Install Python 3.8 or later

Install dependencies:

cd docs
pip install -r requirements.txt

Serve Locally¶

cd docs
mkdocs serve

Access at: http://localhost:8000

Build Static Site¶

cd docs
mkdocs build

Output will be in docs/site/

Deployment Options¶

Option 1: GitHub Pages¶

Install mkdocs-gh-deploy:
```
pip install mkdocs-gh-deploy
```
Deploy to GitHub Pages:
```
cd docs
mkdocs gh-deploy
```

Option 2: Docker Deployment¶

Add a docs service to docker-compose.yml:

  docs:
    image: squidfunk/mkdocs-material:latest
    container_name: azharstore-docs
    volumes:
      - ./docs:/docs
    ports:
      - "8000:8000"
    command: mkdocs serve -a 0.0.0.0:8000
    restart: unless-stopped
    networks:
      - azharstore-network

Start the docs service:

docker compose up -d docs

Access at: http://localhost:8000

Option 3: Static Hosting (Netlify, Vercel, etc.)¶

Build the site:
```
cd docs
mkdocs build
```
Deploy the site/ directory to your hosting provider

Option 4: Cloudflare Pages¶

Cloudflare Pages can automatically build and deploy MkDocs sites from Git.

Via Git Integration¶

Push your code to GitHub/GitLab
In Cloudflare Dashboard:
Go to Pages > Create a project
Connect to your Git provider
Select your repository
Configure build settings:
- Build command: cd docs && pip install -r requirements.txt && mkdocs build
- Build output directory: docs/site
- Root directory: / (repository root)
Click Save and Deploy

Via Direct Upload¶

Build the site locally:

cd docs
pip install -r requirements.txt
mkdocs build

In Cloudflare Dashboard:
Go to Pages > Create a project
Select "Upload assets"
Upload the contents of docs/site/
Click Deploy site

Environment Variables¶

If your documentation needs environment variables, add them in Cloudflare Pages settings: - Go to your Pages project > Settings > Environment variables - Add any required variables

Custom Domain¶

In Cloudflare Pages project:
Go to Custom domains
Add your domain (e.g., docs.azhar.store)
Follow DNS instructions

Option 5: Nginx Deployment¶

Build the site:
```
cd docs
mkdocs build
```

Serve with Nginx:

server {
    listen 80;
    server_name docs.azhar.store;

    root /path/to/docs/site;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Configuration¶

The MkDocs configuration is in mkdocs.yml:

Theme: Material
Plugins: Search, Git revision dates
Extensions: Code highlighting, Mermaid diagrams, Admonitions

Customization¶

Theme¶

Edit the theme section in mkdocs.yml to customize colors, fonts, and features.

Edit the nav section in mkdocs.yml to add or remove pages.

Plugins¶

Add plugins to the plugins section in mkdocs.yml.

CI/CD¶

GitHub Actions¶

Create .github/workflows/docs.yml:

name: Deploy Documentation

on:
  push:
    branches: [main]
    paths: [docs/**, mkdocs.yml]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - run: pip install mkdocs-material mkdocs-git-revision-date-localized-plugin
      - run: mkdocs gh-deploy --force

Troubleshooting¶

Build Errors¶

If you encounter build errors:

Check Python version (>= 3.8)
Reinstall dependencies: pip install -r requirements.txt --upgrade
Check for syntax errors in markdown files

Missing Pages¶

If pages don't appear in navigation:

Check the nav section in mkdocs.yml
Verify file paths are correct
Ensure files are in the docs/ directory

Plugin Errors¶

If plugins fail to load:

Install missing plugins: pip install <plugin-name>
Check plugin configuration in mkdocs.yml
Verify plugin compatibility with MkDocs version