Initial commit

Author: sntxerror

.github/workflows/deploy.yml

@@ -0,0 +1,79 @@
+name: Deploy MkDocs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - site
+  repository_dispatch:
+    types: [modules-updated]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout site branch
+        uses: actions/checkout@v4
+
+      - name: Checkout master branch content
+        uses: actions/checkout@v4
+        with:
+          ref: master
+          path: master-content
+
+      - name: Copy module content from master
+        run: |
+          # Copy README.md as index page
+          cp master-content/README.md docs/index.md
+          echo "Copied README.md -> docs/index.md"
+          
+          # Copy each module directory from master to docs/
+          for dir in master-content/mod-*/; do
+            module=$(basename "$dir")
+            rm -rf "docs/${module}"
+            cp -r "$dir" "docs/"
+            echo "Copied ${module}/"
+          done
+          # Clean up
+          rm -rf master-content
+          echo "=== Module files in docs/ ==="
+          ls -la docs/mod-* | head -30
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Update navigation from H1 titles
+        run: python scripts/update_nav.py
+          
+      - name: Build site
+        run: mkdocs build
+        
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,24 @@
+# Build artifacts
+site/
+
+# Content fetched from master during build
+docs/mod-*/
+docs/index.md
+
+# Python virtual environment
+.venv/
+venv/
+env/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,74 @@
+# Modules - Site Branch
+
+This branch contains the MkDocs build configuration for the MICRORACK Modules documentation.
+
+**⚠️ Do not edit content here directly!** Edit the source markdown files in the `master` branch instead.
+
+## How it works
+
+1. Content is edited in the `master` branch (bare markdown files)
+2. GitHub Actions automatically syncs content to this branch
+3. MkDocs builds and deploys to GitHub Pages
+
+## Branch Structure
+
+### Master Branch (source - bare markdown)
+```
+repo/
+├── README.md                 # Index page content
+├── LICENSE.md                # License file
+├── .github/
+│   └── workflows/
+│       └── sync-to-site.yml  # Sync workflow
+├── mod-vco/
+│   ├── README.md
+│   └── mod-vco.png
+├── mod-vcf/
+│   ├── README.md
+│   └── mod-vcf.png
+└── ... (other modules)
+```
+
+### Site Branch (this branch)
+```
+repo/
+├── README.md                 # This file
+├── mkdocs.yml                # MkDocs configuration
+├── requirements.txt          # Python dependencies
+├── scripts/
+│   └── convert_admonitions.py
+├── .github/
+│   └── workflows/
+│       └── deploy.yml        # Deploy workflow
+└── docs/
+    ├── index.md              # ← synced from master/README.md
+    ├── LICENSE.md            # ← synced from master/LICENSE.md
+    ├── CNAME
+    ├── assets/               # CSS, JS, logos, fonts
+    └── mod-*/                # ← synced from master/mod-*/
+```
+
+## Local Development
+
+```bash
+pip install -r requirements.txt
+mkdocs serve
+```
+
+Visit http://127.0.0.1:8000
+
+## GitHub Configuration
+
+After creating the site branch:
+
+1. **GitHub Pages Settings** (Settings → Pages):
+   - Source: `GitHub Actions`
+
+2. **Add site branch to allowed deployment branches**:
+   ```bash
+   gh api repos/OWNER/REPO/environments/github-pages/deployment-branch-policies \
+     --method POST -f name=site
+   ```
+
+3. **Actions Permissions** (Settings → Actions → General):
+   - Workflow permissions: Read and write permissions

docs/CNAME

@@ -0,0 +1 @@
+modules.microrack.org