--- name: mkdocs-github-pages-deployment description: Use when deploying MkDocs documentation to GitHub Pages with GitHub Actions - covers Python-Markdown gotchas (indentation, footnotes, grid tables), workflow configuration, and systematic markdown fixing --- # MkDocs + GitHub Pages Deployment with GitHub Actions ## Overview This skill documents lessons learned from deploying MkDocs documentation to GitHub Pages using GitHub Actions, including common pitfalls and their solutions. --- ## GitHub Pages Deployment Methods ### Method 1: Legacy `mkdocs gh-deploy` (Deprecated) ```yaml - name: Deploy to GitHub Pages run: mkdocs gh-deploy --force --clean --verbose ``` **Issues:** - Uses legacy deployment method - Requires write access to gh-pages branch - Less transparent in GitHub UI - Harder to debug ### Method 2: GitHub Actions (Recommended) ✅ ```yaml permissions: contents: write pages: write # Required for GitHub Pages id-token: write # Required for OIDC authentication concurrency: group: "pages" cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Build MkDocs site run: mkdocs build --site-dir output\/site - name: Upload artifact for GitHub Pages uses: actions\/upload-pages-artifact@v3 with: path: output\/site deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions\/deploy-pages@v4 ``` **Benefits:** - Modern GitHub Actions workflow - Proper environment tracking - Deployment URL visible in workflow - Better security with OIDC - Clear separation of build and deploy stages --- ## Repository Settings **CRITICAL:** In GitHub repository settings: 1. Go to **Settings → Pages** 2. Under **Source**, select **"GitHub Actions"** (not "Deploy from a branch") 3. This enables the modern deployment method --- ## MkDocs Configuration Issues and Solutions ### Issue 1: Grid Tables Not Rendering **Problem:** Pandoc-style grid tables (used in policy documents) not rendering correctly. **Example of Grid Table Syntax:** ```markdown +-----------------+-----------------+--------------------------------------------------------------+ | **Consequence** | **Consequence** | **Description** | | **Level** | **Score** | | +=================+=================+==============================================================+ | Low | 0 | Loss of confidentiality... | +-----------------+-----------------+--------------------------------------------------------------+ ``` **Solution:** Add `markdown-grid-tables` extension ```yaml # mkdocs.yml markdown_extensions: - markdown_grid_tables # Supports Pandoc\/reStructuredText grid tables ``` **Installation:** ```bash pip install markdown-grid-tables ``` **In GitHub Actions:** ```yaml - name: Install MkDocs and extensions run: | pip install mkdocs-material markdown-grid-tables ``` --- ### Issue 2: Content Rendered as Code Blocks Instead of Lists **Problem:** Nested list items and bullets rendering with line numbers in gray code blocks. **Root Cause:** 1. **4-space indentation creates code blocks** in Markdown (not continuation of lists) 2. **Python-Markdown doesn't recognize `i.` as list markers** (roman numerals not supported) **Example of Broken Markdown:** ```markdown a. **Side-Channel Attack Mitigations:** i. **Timing Attacks:** - All cryptographic operations must be constant-time - Hardware wallets use secure elements ``` **What Happens:** - The ` i. **Timing Attacks:**` (4 spaces) is treated as a code block - Renders with line numbers and gray background - Not formatted as a list item **Solution Part 1: Fix Indentation** Change 4-space indent to 3-space indent: ```markdown a. **Side-Channel Attack Mitigations:** i. **Timing Attacks:** - All cryptographic operations must be constant-time - Hardware wallets use secure elements ``` **Solution Part 2: Use Standard List Markers** Convert `i.` to `1.` (Python-Markdown recognizes numbered lists): ```markdown a. **Side-Channel Attack Mitigations:** 1. **Timing Attacks:** - All cryptographic operations must be constant-time - Hardware wallets use secure elements ``` **Automation Script:** ```python #!\/usr\/bin\/env python3 import re from pathlib import Path def fix_lists(content): """Fix list markers and indentation.""" lines = content.split('\n') fixed_lines = [] for line in lines: # Replace 'i.' with '1.' at any indentation if re.match(r'^(\s+)i\.\s', line): fixed_line = re.sub(r'^(\s+)i\.', r'\g<1>1.', line) fixed_lines.append(fixed_line) else: fixed_lines.append(line) return '\n'.join(fixed_lines) # Apply to all markdown files for md_file in Path('policies').glob('*.md'): content = md_file.read_text() fixed = fix_lists(content) md_file.write_text(fixed) ``` --- ### Issue 3: Footnotes Only Showing First Line **Problem:** Footnotes\/endnotes render with only the heading visible, missing detailed WHAT\/WHY\/WHERE content. **Root Cause:** Python-Markdown footnotes extension requires ALL continuation lines (after the first line) to be indented with exactly 4 spaces. **Example of Broken Markdown:** ```markdown [^15]: ### Side-Channel Attack Mitigations #### WHAT: Requirement Definition Protection against timing attacks... ``` **Result:** Only "### Side-Channel Attack Mitigations" renders in the footnote. **Solution:** Indent ALL continuation lines with 4 spaces: ```markdown [^15]: ### Side-Channel Attack Mitigations #### WHAT: Requirement Definition Protection against timing attacks... #### WHY: Security Rationale - **Timing attacks**: Details here... ``` **Automated Fix:** See `~\/.claude\/skills\/mkdocs-footnotes-formatting.md` for comprehensive guide and automation scripts. **Quick Fix Script:** ```python import re from pathlib import Path def fix_footnote_indentation(content: str) -> str: lines = content.split('\n') result = [] in_footnote = False for line in lines: if re.match(r'^\[\^[0-9]+\]:', line): in_footnote = True result.append(line) continue if in_footnote: if (line.strip() == '---' or re.match(r'^\[\^[0-9]+\]:', line) or re.match(r'^#{1,2}\s+[^#]', line)): in_footnote = False result.append(line) continue if line.startswith(' ') or line.strip() == '': result.append(line) else: result.append(' ' + line) else: result.append(line) return '\n'.join(result) ``` **Impact:** 12 files fixed, 855 lines indented for proper footnote rendering. --- ### Issue 5: WHERE Section Citations Not Using Bullet Points **Problem:** Citation paragraphs in WHERE: Authoritative Sources sections lack visual hierarchy, making it difficult to distinguish individual sources. **Example of Problematic Formatting:** ```markdown #### WHERE: Authoritative Sources Citation text here — Source, Date Another citation — Source, Date ``` **Result:** Renders as plain paragraphs without clear separation between citations. **Solution:** Convert citations to bulleted lists: ```markdown #### WHERE: Authoritative Sources - Citation text here — Source, Date - Another citation — Source, Date ``` **Automated Fix:** ```python import re from pathlib import Path def fix_where_citations(content: str) -> str: """Convert WHERE section citations to bullet points.""" lines = content.split('\n') result = [] in_where_section = False i = 0 while i < len(lines): line = lines[i] if '#### WHERE: Authoritative Sources' in line: in_where_section = True result.append(line) i += 1 # Skip blank line after header if i < len(lines) and lines[i].strip() == '': result.append(lines[i]) i += 1 # Process citations while i < len(lines): current_line = lines[i] # Exit on section boundary if (current_line.strip() == '---' or current_line.strip().startswith('####') or re.match(r'^\[\^[0-9]+\]:', current_line)): in_where_section = False break # Add bullet to citation text if (current_line.strip() != '' and not current_line.lstrip().startswith('—') and not current_line.lstrip().startswith('-')): indent = len(current_line) - len(current_line.lstrip()) citation_text = current_line.strip() result.append(' ' * indent + '- ' + citation_text + ' ') i += 1 # Handle attribution line (starts with —) if i < len(lines) and lines[i].lstrip().startswith('—'): attribution_line = lines[i] attr_indent = len(attribution_line) - len(attribution_line.lstrip()) attribution_text = attribution_line.strip() result.append(' ' * (indent + 2) + attribution_text) i += 1 continue result.append(current_line) i += 1 else: result.append(line) i += 1 return '\n'.join(result) ``` **Impact:** Better visual hierarchy, clearer source attribution, proper HTML `

Parent
- Child<\/li><\/ul><\/li><\/ul>` --- ## Essential MkDocs Extensions ### Complete Configuration ```yaml # mkdocs.yml markdown_extensions: # Core extensions - meta # YAML frontmatter support - admonition # Note\/warning boxes - tables # Standard GFM tables - attr_list # Add attributes to elements - md_in_html # Markdown inside HTML - def_list # Definition lists - footnotes # Footnote support - abbr # Abbreviations with tooltips # Table of contents - toc: permalink: true toc_depth: 3 # PyMdown Extensions for enhanced features - pymdownx.details # Collapsible content blocks - pymdownx.superfences # Enhanced code blocks - pymdownx.highlight: # Code syntax highlighting use_pygments: true linenums: true - pymdownx.inlinehilite # Inline code highlighting - pymdownx.tabbed: # Tabbed content alternate_style: true - pymdownx.tasklist: # Task lists with checkboxes custom_checkbox: true - pymdownx.emoji: # Emoji support emoji_index: !!python\/name:material.extensions.emoji.twemoji emoji_generator: !!python\/name:material.extensions.emoji.to_svg # Grid table support for Pandoc-style tables - markdown_grid_tables ``` --- ## Markdown Best Practices for MkDocs ### List Nesting Rules ```markdown # ✅ CORRECT: 3-space indent for nested lists a. First item 1. Nested item - Bullet under nested item - Another bullet # ❌ WRONG: 4-space indent creates code block a. First item 1. Nested item - This becomes a code block! ``` ### List Marker Support ```markdown # ✅ SUPPORTED by Python-Markdown 1. Numbered list (Arabic numerals) 2. Second item a. Lettered list (lowercase) b. Second item - Unordered list (dashes) - Second item * Unordered list (asterisks) * Second item # ❌ NOT SUPPORTED by Python-Markdown i. Roman numerals (lowercase) ii. Second item I. Roman numerals (uppercase) II. Second item ``` **Key Insight:** Always use `1.` for numbered sublists, not `i.` --- ## Citation and URL Verification ### CRITICAL RULE: Never Hallucinate URLs **Problem:** When adding citations and references to documentation, it's tempting to generate plausible-sounding URLs based on patterns, but this creates broken links and damages credibility. **Example of Hallucination:** ```markdown ❌ BAD: Generated URL based on assumptions — [Organization, project-name - Feature (Lines 89-124)](https:\/\/github.com\/Org\/project\/blob\/main\/src\/file.c#L89-L124) Result: 404 error - repository doesn't exist, file doesn't exist ``` **Correct Approach:** ```markdown ✅ GOOD: Verified URL pointing to actual resource — [Actual Organization, actual-project - Actual Implementation (Lines 47-122)](https:\/\/github.com\/ActualOrg\/actual-project\/blob\/main\/src\/realfile.c#L47-L122) Result: 200 OK - real file with actual implementation ``` ### URL Verification Protocol **ALWAYS follow this sequence when adding citations:** 1. **Search for the actual resource first** ```bash # Use web search to find the correct repository # Browse the actual file structure # Find the real files and functions ``` 2. **Verify URLs return 200 OK** ```bash curl -s -o \/dev\/null -w "%{http_code}" "URL_HERE" # Must return 200 before adding to documentation ``` 3. **Copy actual URLs, don't construct them** - Browse to the file in GitHub - Click on line numbers to get fragment URLs - Copy the full URL from browser - Never type URLs from memory or patterns 4. **If source doesn't exist, say so** - ✅ "Source code reference not publicly available" - ❌ Don't invent a plausible-sounding URL ### Common Hallucination Patterns to Avoid **Pattern 1: Assuming Repository Names** ```markdown ❌ OrgName\/assumed-project # Sounds right, doesn't exist ✅ ActualOrg\/actual-project # Actual repository ``` **Pattern 2: Assuming File Names** ```markdown ❌ src\/signTransaction.c # Common name, doesn't exist ✅ src\/signTransfer.c # Actual file name ``` **Pattern 3: Inventing Line Numbers** ```markdown ❌ Lines 89-124 # Plausible range, made up ✅ Lines 47-122 # Actual function location ``` ### Verification Checklist for Citations Before committing documentation with URLs: - [ ] Every URL tested with curl or browser - [ ] All URLs return 200 OK status - [ ] File paths match actual repository structure - [ ] Line numbers correspond to actual code - [ ] Organization names are correct - [ ] Repository names are exact matches - [ ] No typos in URLs - [ ] Fragment anchors (#L47-L122) work when clicked ### Red Flags That Indicate Hallucination 🚩 "This URL looks right to me" - CHECK IT 🚩 "It follows the pattern" - VERIFY IT 🚩 "It's probably at line X" - FIND THE ACTUAL LINE 🚩 "The repository should be named Y" - SEARCH FOR IT 🚩 Multiple 404 errors found during review - YOU HALLUCINATED ### Recovery from Hallucination If you discover hallucinated URLs: 1. **Acknowledge the error immediately** - Don't rationalize or make excuses - Explain what went wrong 2. **Find the correct URLs** - Search for actual repositories - Browse actual file structures - Verify every single URL 3. **Document the correction** ```bash git commit -m "Fix hallucinated URLs with verified repository paths" ``` 4. **Update the skill doc** (like this section) - Document what you learned - Add patterns to avoid - Help prevent future hallucinations ### Why This Matters **Documentation credibility depends on accuracy.** A single hallucinated URL: - Destroys trust in all other citations - Wastes time for readers following broken links - Makes the documentation look unprofessional - Can mislead people about what actually exists **The correct answer is always:** - "Let me verify that URL first" - "I need to search for the actual repository" - "I'll check if that file exists before citing it" --- ## Testing and Validation ### Local Build Test ```bash # Install dependencies pip install mkdocs-material markdown-grid-tables # Build site mkdocs build --strict --site-dir site-test # Check for errors (--strict makes warnings into errors) # Look for: # - "Error rendering grid table" # - Broken symlinks # - Missing pages in nav # Serve locally for visual inspection mkdocs serve # Clean up test build rm -rf site-test ``` ### What to Check After Building 1. **Grid tables render correctly** (not as plain text) 2. **Nested lists render as HTML lists** (`