MkDocs Deployment Guide¶

Prerequisites¶

Install MkDocs with Material theme:

pip install mkdocs-material pymdown-extensions mkdocs-minify-plugin

Local Development¶

Preview Documentation¶

cd /Volumes/SATECHI_WD_BLACK_2/USL
mkdocs serve

Open http://localhost:8000 in your browser. The site will automatically reload when you make changes.

Build Static Site¶

mkdocs build

This generates static HTML in the site/ directory.

Deploy to GitHub Pages¶

One-Command Deployment¶

mkdocs gh-deploy

This command: 1. Builds the documentation 2. Creates/updates the gh-pages branch 3. Pushes to GitHub 4. Makes site available at https://usl-lang.sshabuj.com (custom domain) or https://shaifulshabuj.github.io/USL/ (GitHub Pages)

Manual Deployment¶

# Build the site
mkdocs build

# Deploy to gh-pages branch
ghp-import -p -f -o site/

Custom Domain Setup¶

Step 1: Add CNAME File¶

Create docs/CNAME with your domain:

usl-lang.dev

Step 2: Configure DNS¶

Add DNS records at your domain provider:

For apex domain (usl-lang.dev):

Type: A
Name: @
Value: 185.199.108.153
Value: 185.199.109.153
Value: 185.199.110.153
Value: 185.199.111.153

For www subdomain:

Type: CNAME
Name: www
Value: shaifulshabuj.github.io

Step 3: Enable Custom Domain in GitHub¶

1. Go to repository Settings
2. Navigate to Pages section
3. Enter your custom domain
4. Enable "Enforce HTTPS"

Step 4: Deploy¶

mkdocs gh-deploy

Allow 24-48 hours for DNS propagation.

CI/CD Integration¶

GitHub Actions Workflow¶

Create .github/workflows/docs.yml:

name: Deploy Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.x

      - name: Cache dependencies
        uses: actions/cache@v3
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: |
          pip install mkdocs-material pymdown-extensions mkdocs-minify-plugin

      - name: Build and deploy
        run: |
          mkdocs gh-deploy --force --clean --verbose

      - name: Verify deployment
        run: |
          sleep 30
          curl -f https://usl-lang.sshabuj.com/ || curl -f https://shaifulshabuj.github.io/USL/ || exit 1

Verification Checklist¶

After deployment, verify:

• Site loads at the correct URL
• All navigation links work
• Search functionality works
• Code blocks render with syntax highlighting
• Mermaid diagrams display correctly
• Dark/light mode toggle works
• Mobile responsive design works
• All tutorials are accessible
• API documentation loads
• Deployment guides are visible

Troubleshooting¶

Site Not Updating¶

Problem: Changes don't appear after deployment

Solution:

# Clear cache and force rebuild
mkdocs build --clean
mkdocs gh-deploy --force

404 Errors¶

Problem: Pages return 404 errors

Solution: - Check mkdocs.yml navigation paths - Ensure file paths are relative to docs/ directory - Verify file extensions are .md - Check for typos in filenames

Build Failures¶

Problem: mkdocs build fails

Solution:

# Check for syntax errors in mkdocs.yml
python -c "import yaml; yaml.safe_load(open('mkdocs.yml'))"

# Validate Markdown files
find docs -name "*.md" -exec python -m markdown {} \; > /dev/null

Custom Domain Not Working¶

Problem: Custom domain shows 404 or doesn't resolve

Solution: 1. Verify CNAME file exists in docs/CNAME 2. Check DNS records with dig usl-lang.dev 3. Wait 24-48 hours for DNS propagation 4. Verify GitHub Pages settings show custom domain

Plugin Errors¶

Problem: Plugins fail to load

Solution:

# Reinstall plugins
pip install --upgrade mkdocs-material pymdown-extensions mkdocs-minify-plugin

# Check plugin configuration in mkdocs.yml

Performance Optimization¶

Enable Caching¶

In mkdocs.yml:

plugins:
  - search
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true
  - offline  # Enable offline viewing

Optimize Images¶

# Install image optimization tools
brew install imageoptim-cli  # macOS
# or
sudo apt-get install optipng jpegoptim  # Linux

# Optimize images in docs/
find docs -name "*.png" -exec optipng {} \;
find docs -name "*.jpg" -exec jpegoptim --strip-all {} \;

Enable CDN¶

Use Cloudflare or similar CDN: 1. Add your domain to Cloudflare 2. Update DNS to Cloudflare nameservers 3. Enable caching and minification 4. Set cache rules for static assets

Monitoring¶

Google Analytics¶

Add to mkdocs.yml:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Check Build Status¶

# View GitHub Actions logs
gh run list --workflow=docs.yml

# View specific run
gh run view <run-id>

Maintenance¶

Regular Updates¶

# Update MkDocs and plugins monthly
pip install --upgrade mkdocs-material pymdown-extensions

# Rebuild and test
mkdocs serve

Broken Link Checking¶

# Install linkchecker
pip install linkchecker

# Build site
mkdocs build

# Check for broken links
linkchecker site/

Content Review¶

• Review tutorials quarterly for accuracy
• Update examples with latest USL syntax
• Add new features to documentation
• Respond to community feedback and issues

Additional Resources¶

• MkDocs Documentation
• Material for MkDocs
• GitHub Pages Documentation
• Markdown Guide

Support¶

For deployment issues: - Open an issue at https://github.com/shaifulshabuj/USL/issues - Check MkDocs documentation - Join USL Discord community - Email: docs@usl-lang.org