UKHO.GitHubCopilot.ToolKit: Instructions file for GitHub Copilot

Documentation authoring rules (docs)

Overview

These instructions define how to create and maintain documentation under ./docs/. They are for contributors who add, update, move, or rename documentation.

Scope

Applies to: docs/**/*.md

• These rules cover document structure, Markdown conventions, linking, and maintenance expectations.
• When multiple instruction files apply, prefer the more specific scope.

Instructions

MUST

• Create documentation under ./docs/ as Markdown files with the .md extension.
• Use semantic Markdown structure with ATX headings (# style).
• Include one (and only one) H1 (#) heading per file.
• Make the H1 the first content in the file.
• Use heading levels in order (do not skip levels, for example, from H2 to H4).
• Use fenced code blocks for code samples and specify the language (for example, csharp, json, xml, bash, powershell).
• Use descriptive link text that explains the target (use the page title or meaningful nouns/verbs).
• Use https links where the target supports it.
• When linking to learn.microsoft.com, omit locale segments (for example, do not include /en-us/ in the URL).
• When linking to other repo files, prefer relative links and use forward slashes (/) in link paths.
• Provide meaningful alt text for images using Markdown image syntax (![alt text](path)).
• When you move or rename documentation files, update inbound and outbound links so navigation remains correct.
• Review the relevant pages under ./docs/wiki/ before drafting planning documents, workflow guidance, or project updates that rely on repository context.
• When completed plan work changes the implemented solution, update the relevant pages under ./docs/wiki/ before the plan is considered complete.
• When any documentation, prompt, agent, template, or workflow change affects project understanding, workflow sequencing, implementation guidance, or usage guidance, update the relevant pages under ./docs/wiki/ before the task is considered complete.
• When ./docs/wiki/ pages are updated, ensure the affected navigation and cross-links continue to resolve.