Authors: Luke Boening, GitHub Copilot (Claude Sonnet 4.5) • Last update: December 14, 2025 02:15:37 • 6 min read

AI Copilot Guide

AI Copilot Guide¶

Tips, prompts, and best practices for working with AI assistants (like GitHub Copilot with Claude Sonnet 4.5) on this documentation project.

Quick Reference¶

Project Context Prompts¶

Use these to give AI context about the project:

"This is a MkDocs documentation site using Material theme, deployed to DreamHost via GitHub Actions"

"The site has custom features including: document statistics, front matter checking, reading time calculation, and text file generation via Pandoc"

"We use YAML front matter with keys: title, description, authors, tags, keywords, topics, categories, status, version, review_cycle_days, last_updated"

Common Tasks¶

Adding a New Document¶

"Create a new markdown file called [name].md in docs/ with appropriate YAML front matter including title, description, authors, tags, and review_cycle_days: 90"

Updating Front Matter¶

"Add [keyword/tag/topic] to the front matter of [filename].md"

"Check all documents for consistent front matter using check_frontmatter.py"

Generating Statistics¶

"Run generate_doc_stats.py to update document statistics"

"Add keyword_count and topic_count to the document statistics report"

Building and Deploying¶

"Build the site with 'mkdocs build' and generate text files with 'python generate_text_docs.py'"

"Update the deploy.yml workflow to include [new step]"

Creating Diagrams¶

"Create a Mermaid flowchart showing [process]"

"Generate a Mermaid class diagram for these database tables: [list tables and relationships]"

Project Structure Understanding¶

Key Files¶

mkdocs.yml              - Main configuration
docs/                   - Markdown source files
site/                   - Built HTML (generated)
requirements.txt        - Python dependencies
.github/workflows/      - Automation workflows
  ├── deploy.yml       - DreamHost deployment
  └── release.yml      - GitHub releases

Important Scripts¶

generate_doc_stats.py    - Creates document statistics
check_frontmatter.py     - Validates YAML consistency
generate_text_docs.py    - Creates plain text versions

Effective AI Prompts¶

Documentation Writing¶

Good prompts:

"Write a technical explanation of [concept] for this Azure sync documentation"
"Create a step-by-step guide for [task] with code examples"
"Add a troubleshooting section for common issues with [feature]"

Include context:

"This is for a Windows Server 2022 environment"
"The audience is IT administrators familiar with PowerShell"
"Keep it concise, use code blocks for commands"

Code Generation¶

Good prompts:

"Create a PowerShell script that [does X] and outputs to JSON"
"Write a Python function to parse YAML front matter and count keywords"
"Add error handling to this script for missing files"

Specify requirements:

"Include docstrings and type hints"
"Add comprehensive error handling"
"Make it compatible with Python 3.8+"

Workflow Automation¶

Good prompts:

"Add a GitHub Actions step to [do something] after building the site"
"Create a workflow that runs on push to main and [actions]"
"Update deploy.yml to include Pandoc installation"

Specify details:

"Run this before/after [existing step]"
"Use Ubuntu latest runner"
"Include error checking and status reporting"

Fixing Issues¶

Good prompts:

"Fix the markdown linting errors in [file]"
"The Mermaid diagram isn't rendering, check the syntax"
"Pandoc isn't found in the GitHub Actions workflow, how to fix?"

Provide error messages:

"Getting this error: [paste full error]"
"The output shows [describe unexpected behavior]"

Context Management¶

What AI Needs to Know¶

Always mention:

Which file you're working with
The goal/outcome you want
Any constraints (format, compatibility, style)

Example:

"In docs/azure-sync.md, add a new section about error handling. 
Include PowerShell code examples. 
Keep the writing style consistent with existing sections."

When AI Gets Confused¶

Reset with context:

"Let's start over. I'm working on a MkDocs site. The file is [name]. 
I need to [specific task]. Here's the current content: [paste section]"

Break down complex tasks:

Instead of: "Update the site with new features"
Try: 
1. "First, add this section to about.md"
2. "Now update mkdocs.yml to include it in nav"
3. "Finally, rebuild and check for errors"

Common Patterns¶

Adding New Features¶

"Create/modify the code or content"
"Update configuration files if needed"
"Add documentation in about.md or relevant page"
"Update requirements.txt if new dependencies"
"Test locally with mkdocs serve"
"Run generate_doc_stats.py"
"Commit and push"

Troubleshooting Workflow¶

"What's the error message?" (paste full output)
"Check if dependencies are installed"
"Verify file paths and permissions"
"Test the isolated component"
"Check GitHub Actions logs if deployment fails"

Documentation Updates¶

"Edit markdown file in docs/"
"Verify front matter is complete"
"Check markdown linting"
"Build locally to preview"
"Run check_frontmatter.py"
"Update document statistics"
"Commit with descriptive message"

Prompts Library¶

Quick Fixes¶

"Fix markdown linting errors"
"Update front matter to include review_cycle_days: 90"
"Add blank lines around lists to fix MD032 errors"
"Remove duplicate heading in [file]"

Analysis¶

"What front matter keys are used in docs/?"
"Show me document statistics for all .md files"
"Which documents are missing tags or keywords?"
"What's the total word count across all documentation?"

Generation¶

"Generate plain text versions of all markdown files"
"Create a document statistics report"
"Generate a tags index page"
"Create a Mermaid diagram showing the deployment workflow"

Validation¶

"Check if all front matter has consistent keys"
"Verify all links in [file] are valid"
"Check if the site builds without errors"
"Validate YAML syntax in mkdocs.yml"

AI Limitations & Workarounds¶

What AI Struggles With¶

File operations:

AI can't directly see your file system
Provide relevant content via copy/paste or describe structure

Binary files:

AI can't read images, PDFs, zip files
Describe what they contain or their purpose

Real-time testing:

AI can't run commands and see output directly
Paste error messages and terminal output

Large file context:

Very long files may be truncated
Focus on specific sections
Use grep/search to find relevant parts

Workarounds¶

Instead of:

"Read all files and fix everything"

Try:

"Check about.md lines 1-50 for [issue]"
"Look at the build output I pasted and suggest fixes"
"Here's the error from generate_doc_stats.py: [error]. How to fix?"

Best Practices¶

Do's¶

✅ Be specific about file names and paths
✅ Include relevant error messages
✅ Mention the goal/desired outcome
✅ Provide context about the environment
✅ Break complex tasks into steps
✅ Verify changes after AI makes them

Don'ts¶

❌ Assume AI remembers previous sessions
❌ Ask vague questions like "make it better"
❌ Expect AI to test/run code directly
❌ Provide partial error messages
❌ Ask to "fix everything" without specifics
❌ Forget to commit changes after modifications

Versioning & Releases¶

Creating a Release¶

"I want to create release v0.3.0. What steps are needed?"

AI will guide you through:
1. Update version numbers in documents
2. Run document statistics
3. Build and test locally
4. Create git tag
5. Push tag to trigger release workflow

Pre-Release Checklist¶

Ask AI to help verify:

"Before releasing, check:
- All front matter is consistent
- Document statistics are updated  
- No markdown linting errors
- Site builds successfully
- Text files are generated
- README is up to date"

Examples of Good Conversations¶

Example 1: Adding New Content¶

User: "I need to document a new PowerShell script for Azure file sync. Where should it go?"

AI: "Add it to docs/azure-sync.md in a new section, or create docs/azure-scripts.md if you have multiple scripts. Include YAML front matter with tags: [Azure, PowerShell, Scripts]"

User: "Create a new section in azure-sync.md about error handling with these error codes: [list]"

AI: Creates formatted section with code examples

Example 2: Fixing Issues¶

User: "Getting error: 'module readtime has no attribute of_text'"

AI: "The readtime module API changed. You're using version 3.x but need 2.x. Run: pip install readtime==2.0.0"

Example 3: Workflow Enhancement¶

User: "Can releases include plain text versions?"

AI: "Yes, update release.yml to install Pandoc and run generate_text_docs.py after building. Here's the change..." Shows specific workflow update

Tips for Long Projects¶

Start sessions with context
"Continuing work on MkDocs site for boening.us"
"Working on the document statistics feature"
Summarize previous work
"Last time we added Pandoc text generation"
"We were fixing markdown linting errors in about.md"
State your current goal
"Now I want to add a search feature"
"Need to update the release workflow"
Reference existing features
"Like we did for document stats..."
"Similar to how we set up the tags plugin..."

Quick Command Reference¶

# Build and preview
mkdocs serve                    # Live preview
mkdocs build                    # Production build

# Generate content
python generate_doc_stats.py    # Update statistics
python generate_text_docs.py    # Create text versions
python check_frontmatter.py     # Validate front matter

# Verify
mkdocs build --strict           # Build with warnings as errors

# Deploy
git push origin main            # Trigger deployment
git tag v0.3.0 && git push origin v0.3.0  # Create release

Getting Help from AI¶

Start with these phrases¶

"How do I [task] in MkDocs?"
"What's the best way to [goal]?"
"Fix this error: [error message]"
"Explain how [feature] works"
"Create a [type] showing [content]"

Provide feedback¶

"That worked, thanks!"
"That didn't work, here's the new error: [error]"
"Close, but I need it to also [additional requirement]"
"Can you simplify this?"

Remember¶

AI is a tool to assist you, not a replacement for understanding. Always:

Review generated code before using it
Test changes locally before committing
Understand what the code/configuration does
Keep backups and use version control
Verify AI suggestions match your requirements

This guide helps you work effectively with AI assistants on documentation projects. Update it as you discover new patterns and workflows.