About This Project¶

Platform: MkDocs Material 9.7.0+
Language: Python 3.12
Hosting: GitHub Pages (free, fast, reliable)
CI/CD: GitHub Actions (auto-deploy on push to main)
Theme: Material for MkDocs (slate color scheme, deep purple/teal accents)
Custom CSS: Snape theme (docs/resources/css/snape.css)

# Literate Navigation (mkdocs-literate-nav)
# SUMMARY.md files define navigation hierarchy
# No more YAML hell in mkdocs.yml

docs/
├── SUMMARY.md              # Main nav
├── cloud/
│   ├── SUMMARY.md          # Cloud section nav
│   └── tools/
│       └── SUMMARY.md      # Cloud tools nav
├── 1337/
│   └── SUMMARY.md          # Cybersecurity nav
└── ...

# Benefits:
# - DRY: Navigation lives next to content
# - Scalable: Nested SUMMARY.md for subsections
# - Git-friendly: Easy to review nav changes in PRs
# - No more: "Where the hell is that page in mkdocs.yml?"

# Code blocks with syntax highlighting
markdown_extensions = [
    "pymdownx.highlight",      # Syntax highlighting (Pygments)
    "pymdownx.superfences",    # Fenced code blocks with features
    "pymdownx.inlinehilite",   # Inline code highlighting
    "pymdownx.snippets",       # Include external files in docs

    # Admonitions (callout boxes)
    "admonition",              # !!! note, !!! warning, etc.
    "pymdownx.details",        # Collapsible admonitions (???)

    # Content tabs
    "pymdownx.tabbed",         # === "Tab 1" syntax

    # Icons and emojis
    "pymdownx.emoji",          # :octicons-heart-16: syntax

    # Tables and lists
    "tables",                  # GitHub-flavored tables
    "def_list",                # Definition lists
    "pymdownx.tasklist",       # - [ ] checkboxes

    # Smart symbols
    "pymdownx.smartsymbols",   # (c) → ©, --> → →

    # Mermaid diagrams
    "pymdownx.superfences",    # Mermaid in code blocks
]

# .github/workflows/gh-pages.yml
name: Deploy MkDocs to GitHub Pages

on:
  push:
    branches: [main]  # Deploy on push to main only

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: 3.12
          cache: pip  # Cache pip dependencies (faster builds)

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Build docs
        run: mkdocs build --strict  # Warnings = errors

      - name: Deploy to gh-pages branch
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

# Local development (live reload)
source venv/bin/activate  # Activate Python virtual environment
mkdocs serve              # http://localhost:8000

# Build validation (strict mode)
mkdocs build --strict     # Warnings treated as errors

# Branch strategy
main       # Production (auto-deploys)
develop    # Development branch
feature/*  # Feature branches from develop

# Git workflow
git checkout -b feature/new-content develop
# Make changes...
mkdocs serve  # Test locally
mkdocs build --strict  # Validate
git add . && git commit -m "feat: add new content"
git push origin feature/new-content
# Create PR to develop → merge → PR to main → auto-deploy

*.cloud.md      # Cloud platforms (AWS, Azure, GCP)
*.tool.md       # Tools (Terraform, kubectl, docker)
*.service.md    # Cloud services (S3, Lambda, etc.)
*.lang.md       # Programming languages (Python, Go, Node.js)
*.1337.md       # Cybersecurity content

## Quick Hits

=== "Essential Syntax/Commands"
    Core concepts, syntax, commands with inline comments

=== "Common Patterns"
    Real-world patterns, workflows, integrations

=== "Pro Tips & Gotchas"
    Best practices, performance tips, common mistakes

# Plugins for speed
plugins:
  - search:
      lang: en
      separator: '[\s\-\.]'  # Faster indexing

  - minify:
      minify_html: true      # Smaller HTML files
      minify_js: true        # Smaller JavaScript
      minify_css: true       # Smaller CSS

# Features for UX
theme:
  features:
    - navigation.instant.loading   # SPA-like navigation
    - navigation.instant.prefetch  # Prefetch on hover
    - search.suggest               # Search autocomplete
    - content.code.copy            # Copy code button

cosckoya.github.io/
├── .github/
│   └── workflows/
│       └── gh-pages.yml        # CI/CD pipeline
├── docs/
│   ├── SUMMARY.md              # Main navigation
│   ├── index.md                # Home page
│   ├── about.md                # This page
│   ├── cloud/                  # Cloud platforms & tools
│   ├── os/                     # Operating systems
│   ├── containers/             # Container tech
│   ├── ai/                     # AI/ML platforms & tools
│   ├── code/                   # Programming languages & tools
│   ├── devops/                 # DevOps tools
│   ├── 1337/                   # Cybersecurity
│   ├── templates/              # Documentation templates
│   └── resources/
│       ├── css/
│       │   └── snape.css       # Custom theme
│       └── img/                # Images and logos
├── mkdocs.yml                  # MkDocs configuration
├── requirements.txt            # Python dependencies
├── venv/                       # Virtual environment
├── CLAUDE.md                   # Claude Code instructions
└── README.md                   # Repository readme

# requirements.txt
mkdocs>=1.5.3
mkdocs-material>=9.7.0
mkdocs-literate-nav>=0.6.1
mkdocs-minify-plugin>=0.8.0
pymdown-extensions>=10.7

# mkdocs.yml (key sections)
site_name: cosckoya's Tech Docs
site_url: https://cosckoya.github.io
repo_url: https://github.com/cosckoya/cosckoya.github.io

theme:
  name: material
  palette:
    - scheme: slate            # Dark mode (default)
      primary: deep purple
      accent: teal
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
    - scheme: default          # Light mode
      primary: deep purple
      accent: teal
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

  features:
    - navigation.instant.loading
    - navigation.instant.prefetch
    - navigation.sections
    - navigation.expand
    - navigation.breadcrumbs
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate

extra_css:
  - resources/css/snape.css    # Custom styling

# Documentation templates (DRY principle)
docs/templates/
├── README.md                    # Template usage guide
├── tech-reference.template.md   # Cloud platforms, major tech
└── tool-reference.template.md   # CLI tools, utilities

# Usage: Replace {{PLACEHOLDER}} values
# Example placeholders:
{{TITLE}}                        # Technology name
{{DESCRIPTION}}                  # One-line SEO description
{{CODE_LANGUAGE}}                # Syntax highlighting
{{TAB_1_TITLE}}                  # First tab name
{{TAB_1_CODE_EXAMPLES}}          # Code examples
{{PRO_TIPS_BULLETS}}             # Expert tips
{{GOTCHAS_BULLETS}}              # Common mistakes

# Production build stats (February 2026)
Pages: 100+
Build time: ~3 seconds
Site size: ~25 MB (minified)
Largest page: ~50 KB (HTML)
Total CSS: ~200 KB (Material theme + custom)
Total JS: ~100 KB (search + instant loading)

# Lighthouse scores (mobile)
Performance: 95/100
Accessibility: 100/100
Best Practices: 100/100
SEO: 100/100

# First visit (cold cache)
HTML: ~50 KB → 200ms (CDN)
CSS: ~200 KB → 300ms (CDN)
JS: ~100 KB → 250ms (CDN)
Search index: ~500 KB → 500ms (CDN)
Total: ~1.25 seconds

# Return visit (warm cache)
HTML: ~50 KB → 50ms (304 Not Modified)
All assets: Cached
Total: ~50ms

# Navigation (instant loading)
Page change: ~50ms (client-side routing)