Copilot Instructions for `docs` (Hugo Site for Azure DevOps Migration Tools)

Copilot Instructions for

docs

(Hugo Site for Azure DevOps Migration Tools)

Purpose

This

docs

folder contains the Hugo static site for Azure DevOps Migration Tools documentation. The site is deployed to Azure Static Web Apps and relies on YAML/Markdown data generated by

src/MigrationTools.ConsoleDataGenerator

This site includes a configuration wizard that guides users through setting up their migration configurations interactively. The wizard is designed to simplify the process of creating complex migration configurations by providing step-by-step instructions and examples. Its documentation is in config-wizard.md.

Key Features:
- Interactive step-by-step configuration setup
- Example configurations for common scenarios
- Validation of user inputs against the schema

Docs & Reference

The

docs\content\docs

directory contains the main documentation sections, including:

Getting Started: Guides for new users to set up and use the migration tools.
How-To Guides: Step-by-step tutorials for common tasks.
Reference Documentation: Detailed information on configuration options, processors. Each page loads its data from YAML files in
```
docs/data/reference/
```
, and should be validated against the schema in
```
docs\static\schema
```
.
Setup Guides: Instructions for installing and configuring the tools.

Key Patterns & Requirements

1. Hugo Site Structure

Use Hugo v0.146+ conventions for content, layouts, and data.
IMPORTANT: This site uses Hugo's new template system (v0.146+) - ensure all template code follows the new patterns and syntax.
Content lives in
```
content/
```
, layouts in
```
layouts/
```
, static assets in
```
static/
```
, and data in
```
data/
```
.
All documentation pages should use Markdown with YAML front matter.
Use shortcodes and partials for reusable content blocks.
Follow the new template system's improved performance and syntax when creating layouts.

Folder Structure

docs/
├── _site-docs            # Contains additional documentation about features in the site itself
├── content/              # Documentation content (Markdown with YAML front matter)
│   ├── docs/             # Main documentation sections
│   │   ├── get-started/  # Getting started guides
│   │   ├── how-to/       # How-to guides and tutorials
│   │   ├── reference/    # Reference documentation
│   │   ├── setup/        # Setup and installation guides
│   │   ├── config-wizard.md # Configuration wizard page
│   │   └── _index.md     # Documentation section index
│   ├── download/         # Download pages and resources
│   ├── support/          # Support and community pages
│   ├── schema/           # JSON schema documentation
│   ├── 404.md            # Custom 404 error page
│   └── _index.md         # Site homepage
├── layouts/              # Hugo templates (HTML with Go templating - v0.146+ new system)
│   ├── docs/             # Section-specific layouts for docs
│   ├── _partials/        # Reusable template components (v0.146+ naming)
│   │   ├── components/   # UI component partials
│   │   ├── docs/         # Documentation-specific partials
│   │   ├── functions/    # Template functions and utilities, they return HTML or data
│   │   ├── JSON-LD/      # Structured data partials
│   ├── _shortcodes/      # Custom Hugo shortcodes (v0.146+ naming)
│   ├── _markup/          # Custom markup renderers
│   ├── baseof.html       # Base template for all pages
│   ├── index.html        # Homepage template
│   ├── single.html       # Single page template
│   ├── list.html         # List page template
│   └── *.html            # Other page-specific templates
├── static/               # Static assets (images, CSS, JS, PDFs)
│   ├── images/           # Documentation images and diagrams
│   ├── css/              # Custom stylesheets
│   └── js/               # JavaScript files
├── data/                 # Generated YAML/JSON data files
│   ├── reference/        # Auto-generated reference docs
│   └── samples/          # Configuration samples
├── hugo.yaml             # Main Hugo configuration
├── hugo.local.yaml       # Local development config
├── hugo.preview.yaml     # Preview environment config
├── hugo.production.yaml  # Production environment config
├── hugo.canary.yaml      # Canary deployment config
└── .hugo_build.lock      # Hugo build lock file

2. Data-Driven Documentation

Reference YAML data files in
```
/docs/_data/
```
generated by
```
MigrationTools.ConsoleDataGenerator
```
for configuration samples, processor options, and reference docs.
Do not manually edit files in
```
/docs/_data/
```
; always regenerate using the ConsoleDataGenerator after code changes.
Use Hugo's
```
data
```
templates to render configuration samples and reference tables from YAML.

3. Documentation Generation Workflow

When processor/option classes change, run the ConsoleDataGenerator to update YAML and Markdown docs.
Validate that generated docs match the current codebase (see root copilot-instructions for checklist).
Use the
```
GenerateDocs.ps1
```
script at the repo root for consistent doc generation.

4. Azure Static Web Apps Deployment

The Hugo site is deployed to Azure Static Web Apps.
Ensure all output is static and compatible with Azure SWA (no server-side code).
Use the
```
staticwebapp.config.json
```
for SWA routing and configuration.
Follow Azure SWA best practices for performance and security.

5. Content & Style Guidelines

Use clear, concise language and consistent formatting.
Prefer code samples and configuration snippets sourced from generated YAML.
Test all configuration samples against the schema documentation to ensure accuracy.
Keep navigation and sidebar structure in sync with generated reference docs.

6. Maintenance

Regenerate docs after any code or configuration option changes.
Review generated Markdown and YAML for accuracy and completeness.
Keep this instruction file up to date with any changes to the documentation workflow or deployment process.

References

Features

Key Features:

Interactive step-by-step configuration setup
Example configurations for common scenarios
Validation of user inputs against the schema

Docs & Reference

The

docs\content\docs

Getting Started: Guides for new users to set up and use the migration tools.

How-To Guides: Step-by-step tutorials for common tasks.

Reference Documentation: Detailed information on configuration options, processors. Each page loads its data from YAML files in

docs/data/reference/

, and should be validated against the schema in

docs\static\schema

Setup Guides: Instructions for installing and configuring the tools.

Key Patterns & Requirements

Use Hugo v0.146+ conventions for content, layouts, and data.

IMPORTANT: This site uses Hugo's new template system (v0.146+) - ensure all template code follows the new patterns and syntax.

Content lives in

content/

, layouts in

layouts/

, static assets in

static/

, and data in

data/

All documentation pages should use Markdown with YAML front matter.

Use shortcodes and partials for reusable content blocks.

Follow the new template system's improved performance and syntax when creating layouts.

docs/
├── _site-docs            # Contains additional documentation about features in the site itself
├── content/              # Documentation content (Markdown with YAML front matter)
│   ├── docs/             # Main documentation sections
│   │   ├── get-started/  # Getting started guides
│   │   ├── how-to/       # How-to guides and tutorials
│   │   ├── reference/    # Reference documentation
│   │   ├── setup/        # Setup and installation guides
│   │   ├── config-wizard.md # Configuration wizard page
│   │   └── _index.md     # Documentation section index
│   ├── download/         # Download pages and resources
│   ├── support/          # Support and community pages
│   ├── schema/           # JSON schema documentation
│   ├── 404.md            # Custom 404 error page
│   └── _index.md         # Site homepage
├── layouts/              # Hugo templates (HTML with Go templating - v0.146+ new system)
│   ├── docs/             # Section-specific layouts for docs
│   ├── _partials/        # Reusable template components (v0.146+ naming)
│   │   ├── components/   # UI component partials
│   │   ├── docs/         # Documentation-specific partials
│   │   ├── functions/    # Template functions and utilities, they return HTML or data
│   │   ├── JSON-LD/      # Structured data partials
│   ├── _shortcodes/      # Custom Hugo shortcodes (v0.146+ naming)
│   ├── _markup/          # Custom markup renderers
│   ├── baseof.html       # Base template for all pages
│   ├── index.html        # Homepage template
│   ├── single.html       # Single page template
│   ├── list.html         # List page template
│   └── *.html            # Other page-specific templates
├── static/               # Static assets (images, CSS, JS, PDFs)
│   ├── images/           # Documentation images and diagrams
│   ├── css/              # Custom stylesheets
│   └── js/               # JavaScript files
├── data/                 # Generated YAML/JSON data files
│   ├── reference/        # Auto-generated reference docs
│   └── samples/          # Configuration samples
├── hugo.yaml             # Main Hugo configuration
├── hugo.local.yaml       # Local development config
├── hugo.preview.yaml     # Preview environment config
├── hugo.production.yaml  # Production environment config
├── hugo.canary.yaml      # Canary deployment config
└── .hugo_build.lock      # Hugo build lock file

Reference YAML data files in

/docs/_data/

generated by

MigrationTools.ConsoleDataGenerator

for configuration samples, processor options, and reference docs.

Do not manually edit files in

/docs/_data/

; always regenerate using the ConsoleDataGenerator after code changes.

Use Hugo's

data

templates to render configuration samples and reference tables from YAML.

When processor/option classes change, run the ConsoleDataGenerator to update YAML and Markdown docs.

Validate that generated docs match the current codebase (see root copilot-instructions for checklist).

Use the

GenerateDocs.ps1

script at the repo root for consistent doc generation.

The Hugo site is deployed to Azure Static Web Apps.

Ensure all output is static and compatible with Azure SWA (no server-side code).

Use the

staticwebapp.config.json

for SWA routing and configuration.

Follow Azure SWA best practices for performance and security.

Use clear, concise language and consistent formatting.

Prefer code samples and configuration snippets sourced from generated YAML.

Test all configuration samples against the schema documentation to ensure accuracy.

Keep navigation and sidebar structure in sync with generated reference docs.

Regenerate docs after any code or configuration option changes.

Review generated Markdown and YAML for accuracy and completeness.

Keep this instruction file up to date with any changes to the documentation workflow or deployment process.

Copilot Instructions for `docs` (Hugo Site for Azure DevOps Migration Tools)

Copilot Instructions for
`docs`
(Hugo Site for Azure DevOps Migration Tools)

Purpose

Features

Config wizard

Docs & Reference

Key Patterns & Requirements

1. Hugo Site Structure

Folder Structure

2. Data-Driven Documentation

3. Documentation Generation Workflow

4. Azure Static Web Apps Deployment

5. Content & Style Guidelines

6. Maintenance

References

Related Skills

Nano Banana Pro

Markdown Converter

1password

Copilot Instructions for
`docs`
(Hugo Site for Azure DevOps Migration Tools)

Purpose

Features

Config wizard

Docs & Reference

Key Patterns & Requirements

1. Hugo Site Structure

Folder Structure

2. Data-Driven Documentation

3. Documentation Generation Workflow

4. Azure Static Web Apps Deployment

5. Content & Style Guidelines

6. Maintenance

References