Home › Agent workflows › Markdown docs Copilot path instructions

Markdown docs Copilot path instructions

Path-specific Copilot instructions for Markdown docs and READMEs: structure, runnable commands, and concise style.

GitHub CopilotAgent workflows

How to use

Save this as .github/instructions/docs.instructions.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
applyTo: "**/*.md,docs/**"
description: How to write documentation in this repo
---

# Documentation (Markdown)

- Start with what the reader is trying to do. Headings are tasks ("Run the tests"), not nouns ("Testing").
- Commands go in fenced code blocks with a language (`bash`), exactly as typed, one command per line, no `$` prompts.
- Show expected output or results when it isn't obvious.
- Short sentences, active voice, second person. Define acronyms once.
- Use relative links to files in the repo; link to sources instead of duplicating them.
- Tables for options/env vars: name, required, default, description.
- Keep examples realistic and copy-pastable; use placeholders like `<your-project-id>` consistently.
- Don't hard-wrap prose mid-sentence if the repo doesn't; follow `markdownlint` config if present.
- Update the "last verified" version note when you change instructions for a tool version.
- Never paste secrets, internal URLs, or personal data into docs.

## Check
Run every command you added on a clean checkout when feasible, and run `npx markdownlint-cli2 "**/*.md"` if configured.