GitHub Workflows¶

This directory contains GitHub Actions workflows for VimAbl.

Workflows¶

Documentation (`docs.yaml`)¶

Automatically builds and deploys MkDocs documentation.

Triggers:

Push to main or feature/docs branches
Pull requests to main
Manual workflow dispatch

Jobs:

build - Build documentation with auto-generation
deploy - Deploy to GitHub Pages (main branch only)
pr-comment - Comment on PR with preview info
validate - Validate links and check for warnings

Auto-Generation:

Commands table from src/remote_script/commands.py
Keybindings table from src/hammerspoon/keys/*.lua
Observers table from src/remote_script/observers.py

Output:

Deployed to: https://<username>.github.io/VimAbl/
PR preview artifact available for download

Setup¶

See SETUP_GITHUB_PAGES.md for detailed setup instructions.

Quick setup:

Enable GitHub Pages in repository settings
Set source to "GitHub Actions"
Push this workflow to main branch
Documentation will auto-deploy

Workflow Features¶

✅ Automatic Documentation Generation¶

The workflow extracts documentation from source code:

# Generated files (not committed)
docs/_auto-generated/
├── commands-table.md       # All TCP commands
├── keybindings-table.md    # All keybindings
└── observers-table.md      # All OSC events

✅ Link Validation¶

Checks for:

Broken internal links
Missing files
Build warnings

✅ PR Preview¶

On pull requests:

Builds documentation
Posts comment with status
Uploads preview artifact

✅ Deployment Protection¶

Only deploys on push to main
Requires successful build
Single concurrent deployment

Local Testing¶

Test the workflow locally before pushing:

# Install dependencies
uv pip install mkdocs-material mkdocs-git-revision-date-localized-plugin

# Generate auto-docs
mkdir -p docs/_auto-generated
python tools/extract_commands.py > docs/_auto-generated/commands-table.md
python tools/extract_keybindings.py > docs/_auto-generated/keybindings-table.md
python tools/extract_observers.py > docs/_auto-generated/observers-table.md

# Build documentation
mkdocs build --strict

# Serve locally
mkdocs serve

Customization¶

Add New Auto-Generation¶

Create extraction script in tools/
Add step to workflow:

- name: Generate new docs
  run: python tools/extract_new.py > docs/_auto-generated/new.md

Change Deployment Branch¶

Edit workflow:

on:
  push:
    branches: [production] # Change from 'main'

Add Deployment Approval¶

Settings → Environments → New environment
Name: github-pages
Add required reviewers
Workflow will wait for approval before deploy

Monitoring¶

View Workflow Runs¶

GitHub UI:

Go to Actions tab
Select Documentation workflow
View run history and logs

Build Badge¶

Add to README.md:

[![Docs](https://github.com/<user>/VimAbl/actions/workflows/docs.yaml/badge.svg)](https://github.com/<user>/VimAbl/actions/workflows/docs.yaml)

Notifications¶

Enable email:

Profile → Settings → Notifications
Actions → Send notifications for failed workflows

Troubleshooting¶

Build Fails¶

Check logs:

# GitHub Actions tab → Failed run → build job → Expand failed step

Common issues:

Missing dependencies → Update Install dependencies step
Broken links → Fix links in markdown files
Invalid YAML → Check mkdocs.yml syntax

Deployment Fails¶

Check permissions:

Settings → Actions → General
Workflow permissions: "Read and write"
Allow PR creation: Enabled

Check Pages settings:

Settings → Pages
Source: "GitHub Actions" (not "Deploy from a branch")

Auto-Generation Fails¶

Verify scripts exist:

ls -la tools/extract_*.py

Test locally:

python tools/extract_commands.py
# Should output markdown table

Security¶

Workflow Permissions¶

The workflow has minimal permissions:

contents: read - Read repository files
pages: write - Deploy to GitHub Pages
id-token: write - OIDC token for deployment
pull-requests: write - Comment on PRs

Secrets¶

No secrets required for basic operation.

If needed:

Settings → Secrets and variables → Actions
New repository secret
Use: ${{ secrets.SECRET_NAME }}

Performance¶

Typical build time:

Build job: ~2 minutes
Deploy job: ~30 seconds
Total: ~2.5 minutes

Optimization tips:

Cache Python dependencies (already configured)
Use --strict mode to catch errors early
Minimize file changes to reduce build time

Future Enhancements¶

Planned improvements:

Deploy preview sites for PRs (Netlify/Vercel)
Link checking with external validator
Documentation coverage metrics
Auto-update changelog from commits
Accessibility testing

Support¶

GitHub Actions: https://docs.github.com/en/actions
MkDocs: https://www.mkdocs.org/
Material Theme: https://squidfunk.github.io/mkdocs-material/

Last Updated: 2025-11-17