Prompts and Markdown Structure for a Documentation Site

tech
github-copilot
prompt-engineering
documentation
Complete guide to structuring repositories with prompts, templates, instructions, and metadata for AI-enhanced documentation workflows
Author

Dario Airoldi

Published

December 26, 2025

Prompts and Markdown Structure for a Documentation Site

Overview

Building an AI-enhanced documentation site requires careful organization of automation tools, content templates, and contextual materials. This article provides a comprehensive guide to structuring your repository with prompt files for task automation, templates for consistent content creation, instruction files for AI guidance, and embedded metadata for tracking validations. By implementing this structure, you’ll create a powerful workflow where GitHub Copilot can generate, review, and validate documentation according to your editorial standards, ensuring consistency and quality across your entire learning site.

Table of Contents

📝 Prompt Files for Task Automation

Prompt files are the backbone of an AI-enhanced documentation workflow. Each prompt automates a specific task, making it easy to maintain quality and consistency across your documentation site. Store these files in .github/prompts/ for automatic recognition by both VS Code and Visual Studio.

Content Generation Prompts

Article Writing (article-writing.prompt.md)
Generates complete draft articles from a topic and outline. This prompt leverages #fetch to retrieve authoritative sources and research, enriching the content with verified information. It follows your article templates to ensure structural consistency and includes proper metadata initialization.

Quality Validation Prompts

Grammar Review (grammar-review.prompt.md)
Performs comprehensive grammar, spelling, and punctuation checks. This prompt identifies errors, suggests corrections, and updates the article’s embedded validation metadata with results. It implements validation caching to avoid redundant checks on unchanged content.

Readability & Redundancy Review (readability-review.prompt.md)
Evaluates writing clarity, consistency, and flow. It calculates readability scores (Flesch-Kincaid), identifies redundant content, checks terminology consistency, and suggests improvements for better comprehension. Results are tracked in the article’s embedded metadata.

Understandability Review (understandability-review.prompt.md)
Assesses whether content effectively communicates to the target audience. This prompt evaluates concept clarity, identifies assumption gaps, checks progressive complexity, and ensures examples support explanations appropriately for the intended reader level.

Structure Validation (structure-validation.prompt.md)
Verifies articles contain all required components: table of contents, introduction, proper heading hierarchy, conclusion, references section, and embedded metadata. It ensures compliance with your documentation templates and standards.

Facts Checking (fact-checking.prompt.md)
Validates factual accuracy against authoritative sources. This prompt identifies claims requiring verification, checks information currency, validates citations, and confirms that references actually support stated facts. It uses #fetch to retrieve and verify source content.

Logic Analysis (logic-analysis.prompt.md)
Examines logical flow and conceptual connections throughout articles. It checks whether ideas build coherently, concepts are introduced before use, transitions are smooth, and no logical leaps exist. This ensures articles follow sound pedagogical structure.

Analysis and Discovery Prompts

Gap Analysis (gap-analysis.prompt.md)
Identifies missing information by comparing article content to authoritative sources. It discovers omitted concepts, unexplained prerequisites, common reader questions not addressed, and related topics that should be linked or covered.

Series Validation (series-validation.prompt.md)
Reviews multiple related articles to ensure logical progression, consistent terminology, appropriate cross-referencing, and non-redundancy. This prompt is essential for multi-part tutorials or article series, maintaining coherence across the entire collection.

Correlated Subjects Discovery (correlated-topics.prompt.md)
Suggests related topics, prerequisite knowledge, and advanced follow-up subjects based on article content. It helps build comprehensive learning paths by identifying connections between topics and discovering content opportunities.

Prompt Configuration Features

Each prompt can leverage powerful IDE features:

  • VS Code: Use \${input:...}\ variables for parameters, #fetch for web content retrieval, #codebase for repository searches, and #file for specific file references
  • Visual Studio (v17.10+): Trigger prompts via #promptName syntax and use #file references for content specification
  • Model Selection: Configure preferred AI models (e.g., claude-sonnet-4.5, gpt-4o) in prompt frontmatter
  • Agent Modes: Specify agent: ask for analysis, agent: edit for direct modifications, or agent: agent for complex workflows

📋 Template Files for Consistent Structure

Templates ensure uniformity across your documentation site. Maintain these in .github/templates/ for easy reference by both humans and AI assistants.

Article Templates

article-template.md
Defines the standard article structure including dual YAML blocks (Quarto metadata at top, Article additional metadata in HTML comment at bottom), title, introduction, table of contents, body sections with proper heading hierarchy, conclusion, and references section. This template serves as the blueprint for all educational content.

howto-template.md
Specialized structure for procedural guides, emphasizing step-by-step instructions, prerequisites section, expected outcomes, troubleshooting tips, and verification steps. Ideal for tutorials and how-to guides.

tutorial-template.md
Long-form instructional content template with learning objectives, prerequisite knowledge, hands-on exercises, checkpoint validations, and next steps for continued learning.

Workflow Templates

issue-template.md
Standardized format for reporting problems, tracking discrepancies, or suggesting improvements. Includes sections for description, reproduction steps, expected vs. actual behavior, context information, and resolution tracking.

recording-summary-template.md
Structure for documenting recorded sessions, interviews, or presentations. Includes metadata (date, participants, duration), segment summaries with timestamps, key points extraction, and action items.

recording-analysis-template.md
Deeper analysis framework for recorded content, identifying themes, patterns, unanswered questions, insights, and follow-up research directions.

📚 Context and Instruction Files

Context files guide AI assistants to produce higher-quality, more consistent outputs aligned with your editorial standards and domain knowledge.

Global Instructions

.github/copilot-instructions.md
Your site’s editorial constitution. This file codifies universal standards such as:

  • Cross-verification of facts with authoritative sources
  • Citation requirements for all claims
  • Readability targets (sentence length, grade level)
  • Required article structure (TOC, introduction, conclusion, references)
  • Dual metadata block architecture rules
  • Validation caching policies

These instructions apply automatically in VS Code and Visual Studio (v17.10+) when “Use Instruction Files” is enabled. They influence every AI interaction within your workspace.

Scoped Instructions

.github/instructions/
File- or directory-specific guidelines that override or extend global instructions. Examples:

documentation.instructions.md (applies to **/*.md)
Enforces Markdown style rules, heading conventions, link formatting, and code block standards across all documentation.

prompts.instructions.md (applies to tech/PromptEngineering/**/*.md)
Specialized rules for prompt engineering content, emphasizing practical examples, tool-specific guidance, and version-specific feature documentation.

tech-articles.instructions.md (applies to tech/**/*.md)
Technical accuracy requirements, code example standards, version specification mandates, and security consideration checklists for technical content.

Extended Context Materials

.copilot/context/
Supporting materials that enhance AI understanding of your domain and standards:

dual-yaml-helpers.md
Complete guide to parsing and updating dual YAML metadata blocks, including code examples, schemas, and validation rules.

validation-schemas.md
Detailed schemas for all validation types (grammar, readability, facts, logic, structure, understandability) with expected outcomes and metrics.

glossary.md
Domain-specific terminology definitions ensuring consistent usage across all content.

style-guide.md
Writing conventions, formatting standards, and editorial preferences specific to your documentation site.

GitHub Copilot’s semantic search prioritizes content in .copilot/context/, making this directory highly effective for storing reference materials that should influence AI outputs.

🏷️ Article Metadata Management

Effective metadata tracking enables validation caching, prevents redundant AI calls, and maintains audit trails of content quality checks.

Dual YAML Block Architecture

This repository implements a dual metadata system that separates concerns while keeping all data with the article:

Top YAML Block (Quarto Metadata)
Standard frontmatter at the file beginning with --- delimiters:

---
title: "Prompts and Markdown Structure for a Documentation Site"
author: "Dario Airoldi"
date: "2025-11-23"
categories: [prompt engineering, documentation, workflow]
description: "Comprehensive guide to organizing prompt files, templates, and metadata for AI-enhanced documentation sites"
---

This block contains document properties used by Quarto for site generation and is modified manually by authors.

Bottom HTML Comment Block (Article Additional Metadata)
Embedded at the file end within HTML comment tags for complete invisibility in rendered output:

<!-- 
---
validations:
  grammar:
    last_run: "2025-11-23T10:30:00Z"
    model: "claude-sonnet-4.5"
    outcome: "passed"
    issues_found: 0
    notes: "No errors detected"
  readability:
    last_run: "2025-11-23T10:35:00Z"
    flesch_score: 65
    grade_level: 9.2
    outcome: "passed"
  structure:
    last_run: "2025-11-23T10:40:00Z"
    has_toc: true
    has_introduction: true
    has_conclusion: true
    has_references: true
    outcome: "passed"
  facts:
    last_run: "2025-11-20T14:00:00Z"
    model: "claude-sonnet-4.5"
    sources_checked: 5
    outcome: "passed"
  logic:
    last_run: "2025-11-23T11:00:00Z"
    flow_score: 8
    outcome: "passed"
  understandability:
    last_run: "2025-11-23T11:15:00Z"
    target_audience: "intermediate"
    comprehension_score: 8
    outcome: "passed"
article_metadata:
  filename: "04. Prompts and markdown structure for a documentation site.md"
  created: "2025-11-15"
  last_updated: "2025-11-23"
  version: "1.2"
  status: "published"
  word_count: 2850
  primary_topic: "Prompt Engineering"
cross_references:
  related_articles:
    - "03. Effective GitHub Copilot prompt files.md"
    - "05. AI-assisted content validation workflows.md"
  series: "Prompt Engineering for Documentation"
  prerequisites: []
---
-->

This block is managed by validation prompts and tools, never by manual editing or document rendering systems.

Embedded Metadata Benefits

Atomicity: Article and its validation history travel together. No orphaned metadata files when articles are moved or renamed.

Invisibility: HTML comments are completely hidden in rendered output, keeping reader-facing content clean.

Automatic Sync: Tools like IQPilot automatically update article_metadata.filename when articles are renamed, maintaining perfect synchronization.

Validation Caching: Prompts check last_run timestamps and content hashes to skip redundant validations, reducing AI API costs by 80-90%.

Audit Trail: Complete history of quality checks, models used, and outcomes provides accountability and continuous improvement insights.

Single Source of Truth: No confusion about which metadata file corresponds to which article or whether metadata is current.

🎯 Implementation Best Practices

Start with Templates: When creating new content, always begin with the appropriate template from .github/templates/. Templates include pre-initialized metadata blocks and proper structure.

Enable Instruction Files: In VS Code settings or Visual Studio options, enable “Use Instruction Files” to automatically apply editorial standards from .github/copilot-instructions.md and scoped instructions.

Leverage Validation Caching: Run validation prompts incrementally as you edit. Prompts check timestamps and skip unnecessary work, making frequent validation checks cost-effective.

Maintain Context Materials: Keep .copilot/context/ updated with current standards, schemas, and domain knowledge. This directory has high semantic search priority.

Use Consistent Naming: Follow naming conventions for prompt files (task-name.prompt.md), templates (type-template.md), and instruction files (scope.instructions.md).

Document Custom Prompts: When creating specialized prompts, include clear frontmatter describing the prompt’s purpose, required inputs, and expected outputs.

Version Control Metadata: Track changes to embedded metadata blocks in git to understand content evolution and validation history over time.

Regular Metadata Review: Periodically check articles for outdated validations (e.g., facts checked more than 30 days ago, grammar not checked in 7+ days) and re-run appropriate prompts.

📖 References

GitHub Copilot Documentation - Prompt Files
https://docs.github.com/en/copilot/using-github-copilot/prompt-engineering-for-github-copilot
Official documentation for creating and using prompt files in VS Code and Visual Studio. Essential reading for understanding prompt file syntax, variables, tool references, and best practices for effective prompt engineering.

Visual Studio 2022 v17.10+ - GitHub Copilot Prompt Files
https://learn.microsoft.com/en-us/visualstudio/ide/copilot-chat-context
Microsoft’s guide to using GitHub Copilot prompt files in Visual Studio, including #file references, #promptName syntax, and integration with Visual Studio’s context features.

Quarto Publishing System
https://quarto.org/docs/reference/
Documentation for Quarto’s YAML frontmatter structure and metadata handling. Critical for understanding how the top YAML block integrates with static site generation and why separating it from validation metadata is important.

YAML Specification
https://yaml.org/spec/1.2.2/
Complete YAML syntax specification. Useful reference for ensuring valid YAML structure in both frontmatter and embedded metadata blocks, avoiding parsing errors that could break automation.

Markdown Specification (CommonMark)
https://spec.commonmark.org/
Authoritative Markdown specification ensuring your templates and articles use valid, portable Markdown syntax that renders consistently across different platforms and tools.

GitHub Copilot Best Practices
https://github.blog/developer-skills/github/how-to-write-better-prompts-for-github-copilot/
GitHub’s official guide to writing effective prompts for Copilot. Provides insights into prompt structure, context provision, and techniques for getting higher-quality AI outputs.

VS Code GitHub Copilot Extension Documentation
https://code.visualstudio.com/docs/copilot/overview
Comprehensive guide to using GitHub Copilot in VS Code, including chat features, inline suggestions, workspace context, and instruction file configuration.

Semantic Search and AI Context Management
https://github.blog/ai-and-ml/github-copilot/how-github-copilot-is-getting-better-at-understanding-your-code/
Explains how GitHub Copilot uses semantic search to prioritize relevant context from your workspace, including the special role of context directories in improving AI understanding and output quality.