markdown · microsoft — Claude Code rule: what it does, how to install
Defines Markdown conventions and YAML frontmatter requirements across all .md files. Keeps Claude Code aligned with markdownlint rules.
MIT ★ 1,627 updated 2026-10-25
.github/instructions/markdown.instructions.mdWhat markdown does
This rule mirrors the .markdownlint.json configuration to keep project documentation consistent. Every markdown file must begin with YAML frontmatter delimiters. Required keys depend on file paths: documentation and root community files require title and description, while instruction files need description and applyTo. All dates must use ISO 8601 formatting (YYYY-MM-DD).
Headings follow ATX syntax starting at column one, with no trailing punctuation. Whenever frontmatter includes a title attribute, writers must start body content at level two (##); adding an H1 tag directly triggers MD025 and MD041 validation errors. Unordered lists require the * marker with two spaces for nested levels.
What it helps with
- format YAML frontmatter against project schemas
- prevent MD025 and MD041 violations when frontmatter has a title
- standardize heading levels and list indentation for markdownlint
- apply ISO 8601 date formatting to document metadata
Example prompts for the agent
- Draft
docs/architecture.mdwith appropriate frontmatter fields and H2 headings - Align list indentation and heading markers in
README.mdwith markdownlint rules - Add metadata and author details to
docs/deployment.md
How to install markdown
Manually: put the files in place
.github/instructions/markdown.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.claude/rules/markdown.mdThe paths frontmatter field limits the files: move applyTo from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/markdown.mdcFrontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own
Manually: put the files in place
.devin/rules/markdown.mdManually: put the files in place
.clinerules/markdown.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about markdown
How do I install markdown in Claude Code?
Save the rule contents into .claude/rules/markdown.md in your project root.
What does the markdown rule enforce?
It enforces consistent ATX headings, two-space list nesting, and required YAML frontmatter properties across Markdown files.
Why is H1 disallowed when YAML frontmatter has a title field?
The frontmatter title satisfies rules MD025 and MD041, so an extra top-level heading creates an invalid second document title.
Source text
markdown.instructions.md · MIT
--- description: "Markdown authoring conventions for all .md files" applyTo: '**/*.md' --- # Markdown Instructions These instructions define the Markdown style guide enforced by markdownlint in this codebase. Follow them when creating or updating any `.md` file here. Examples are included in XML-style blocks that downstream tools can extract. ## Scope * Applies to all Markdown files in this codebase excluding files with `<!-- markdownlint-disable-file -->`. * Mirrors the active configuration in `.markdownlint.json`. * When in doubt, prefer clarity and consistency. Automated fixes are acceptable if they preserve intent. ## General conventions * Use UTF-8 and plain ASCII punctuation unless content requires otherwise. * Prefer descriptive headings and concise paragraphs; avoid trailing or leading extra spaces. * Keep lines reasonably short for readability; wrap where sensible without breaking URLs or code. ## Headings * Start documents with a single level-1 heading that acts as the title when appropriate. * Increase heading levels by one at a time; do not skip levels. * Use a consistent heading style per file. Prefer ATX style (`#`, `##`, `###`, ...) for new content. * Do not indent headings; they must start at column 1. * Surround each heading with a blank line above and below (except at file start/end). * Do not end headings with punctuation such as `. , ; : !` or their full-width variants. * Avoid duplicate headings under the same parent section; make them unique. * Do NOT use an H1 heading when YAML frontmatter contains a `title:` field. The frontmatter title satisfies MD025 and MD041. Start content with H2 or below after frontmatter. If no frontmatter exists, begin the file with a top-level heading. * Use exactly one space after the `#` characters in headings; do not omit or use multiple spaces. * If you close ATX headings with trailing `#` characters, use a single space between the text and both the opening and closing hashes; do not use multiple spaces on either side. * Use only one top-level heading per document; subsequent sections must use lower levels. <!-- <example-headings> --> ```markdown # Title ## Section ### Subsection ``` <!-- </example-headings> --> ## YAML Frontmatter * All markdown files MUST include YAML frontmatter at the beginning of the file * Frontmatter MUST be the first content in the file (before H1 heading) * Use triple-dash delimiters (---) on separate lines to wrap frontmatter YAML * Frontmatter provides machine-readable metadata for validation, SEO, and site generation * Do NOT use an H1 heading when frontmatter includes a `title:` field; the title in frontmatter acts as the document title per MD025/MD041 * Start document content with H2 or below when frontmatter contains a `title:` field ### Required Fields by File Type | File Type | Required Fields | Schema File | |---------------------------------------------------------|--------------------------|------------------------------------------| | Root community files (README.md, CONTRIBUTING.md, etc.) | `title`, `description` | `root-community-frontmatter.schema.json` | | Documentation files (`docs/**/*.md`) | `title`, `description` | `docs-frontmatter.schema.json` | | Instruction files (`.github/**/*.instructions.md`) | `description`, `applyTo` | `instruction-frontmatter.schema.json` | | Agent files (`.github/**/*.agent.md`) | `description` | `agent-frontmatter.schema.json` | | Prompt files (`.github/**/*.prompt.md`) | `description` | `prompt-frontmatter.schema.json` | ### Recommended Fields * `author`: Author or team responsible for the content * `ms.date`: Last modified date in ISO 8601 format (YYYY-MM-DD) * `ms.topic`: Documentation topic type (overview, concept, tutorial, reference, how-to, troubleshooting) * `keywords`: Array of keywords for content categorization * `estimated_reading_time`: Positive integer (minutes) ### Date Format * MUST use ISO 8601 format: YYYY-MM-DD (e.g., `ms.date: 2025-11-15`) * Do NOT use MM/DD/YYYY, DD/MM/YYYY, or other formats ### Schema Validation * Schemas define required and optional frontmatter fields per file type * Pattern-based mapping determines which schema applies to each file * VS Code YAML extension (`redhat.vscode-yaml`) provides in-editor validation when schemas are configured * Run the repository's frontmatter validation if available (check `package.json` for a validation command) ### Schema Pattern Matching Files are validated against schemas based on glob pattern matching: * Patterns are evaluated in order from most specific to least specific * First matching pattern determines the schema * If no pattern matches, `base-frontmatter.schema.json` is used as default * Pattern syntax supports: * `**` for recursive directory matching * `*` for single path segment wildcard * `|` for alternation (e.g., `README.md|CONTRIBUTING.md`) Pattern examples: * `.github/**/*.instructions.md` - All instruction files in .github directory tree * `docs/**/*.md` - All markdown files under docs directory * `README.md|CONTRIBUTING.md` - Exact filename match (alternation) ### Examples <!-- <example-frontmatter-docs> --> ```yaml --- title: Getting Started Guide description: Quick setup guide for configuring your project author: Your Team ms.date: 2025-11-15 ms.topic: tutorial keywords: - setup - getting started estimated_reading_time: 5 --- ## Getting Started This guide shows you how to configure your project... ``` <!-- </example-frontmatter-docs> --> <!-- <example-frontmatter-instructions> --> ```yaml --- description: "Required instructions for creating or editing any Markdown (.md) files" applyTo: '**/*.md' --- # Markdown Instructions These instructions define the Markdown style guide... ``` <!-- </example-frontmatter-instructions> --> ## Lists * Use unordered list markers consistently across a file; for the same level, do not mix `*`, `+`, `-`. * Try to always use `*` for unordered lists. * Avoid using `-` and `+` for unordered lists unless the file already uses these. * Indent unordered sublist content by 2 spaces per level. * Keep indentation consistent for items at the same nesting level. * Use one space between any list marker and the list text for both ordered and unordered lists. * Surround lists with a blank line before and after (unless at file start/end). * For ordered lists, either use `1.` for all items or increment numerically; do not mix styles within a list. Leading zeros are allowed only when used consistently. <!-- <example-lists> --> ```markdown * Item 1 * Item 2 * Nested item 1. Step 2. Step 3. Step ``` <!-- </example-lists> --> ### Bullet point punctuation Follow professional editorial standards for bullet point punctuation consistency: * **Fragment bullet points** (short phrases, technical terms, simple commands): Do NOT end with periods. * **Complete sentence bullet points** (subject + verb constructions): End with periods. * Based on Google, Microsoft, and GitLab style guidelines <!-- <example-bullet-punctuation> --> ```markdown * Configuration file * API endpoint * User authentication * Enable debugging mode * This function validates the input parameters * The system processes requests asynchronously * Users can configure settings through the UI * When enabled, it provides detailed logging information ``` <!-- </example-bullet-punctuation> --> ## Code blocks and code spans * Use fenced code blocks consistently (prefer triple backticks) and surround them with a blank line before and after. Use fenced code instead of indented code blocks. * Always specify a language for fenced code blocks; use `text` if no highlighting is desired. * Avoid tabs; use spaces everywhere. Do not include hard tab characters in code, lists, or text. * Do not add spaces just inside backticks of code spans; write `` `code` `` not `` ` code ` ``. * For shell examples, do not prefix commands with `$` unless you also show the command output; prefer copy-pasteable commands without the prompt. * Use backticks for code fences consistently across the repository; do not use tildes. <!-- <example-code> --> ````markdown ```bash # Good echo "Hello" ``` Some inline `code` here. ```` <!-- </example-code> --> ## Links and images * Do not reverse link syntax; write `[text](url)`. * Do not use empty links like `[]()` or `(#)`; always provide a valid destination. * Avoid bare URLs; wrap them in angle brackets like `<https://example.com>` or make them proper links with text. * Ensure link fragments match generated heading IDs (kebab-case, lower-case). Use `<a id="...">` when needed. * Provide alternate text for all images. If an image must be hidden from assistive tech, use `aria-hidden="true"` in HTML. * Keep spaces out of link text brackets: `[text]`, not `[ text ]`. * Use a consistent link/image style within a document. Inline and autolink styles are allowed. When using full `[text][label]` or collapsed `[label][]` references, ensure the corresponding `[label]: URL` is defined. Remove unused or duplicate reference definitions. * If literal bracketed text is intended (not a link), escape the brackets as `\[text\]`. <!-- <example-links-images> --> ```markdown See <https://example.com> and [Docs](https://example.com/docs).  ``` <!-- </example-links-images> --> ## Spacing and blank lines * Limit paragraph and prose lines to approximately 500 characters; keep headings under 80 characters. * Do not add trailing spaces at the end of lines except when intentionally forcing a hard line break; when forcing breaks, use exactly two spaces. * Do not use multiple consecutive blank lines; keep at most one in a row. * Surround fenced code blocks, headings, lists, and tables with a blank line before and after (unless at file start/end). * Files must end with a single newline; no extra blank lines at EOF. * Do not break long URLs or long words to satisfy line length. Headings should honor their shorter limit; tables are exempt from line length checks. Code blocks may exceed normal line length; avoid wrapping code for width alone. ## Blockquotes * Use a single space after the `>` marker; avoid multiple spaces. * Do not place a bare blank line between adjacent blockquotes unless they are the same quote (then include `>` on the blank line to continue it). * Inside blockquotes, apply the same list and code rules; when creating tight lists with code fences inside blockquotes, consider whether a blank line is required for your target renderer. <!-- <example-blockquotes> --> ```markdown > Quoted text continues > > Same quote after a blank line. ``` <!-- </example-blockquotes> --> ## Horizontal rules * Use one horizontal rule style consistently within a document. Prefer `---`. ## Emphasis * Use a consistent style for emphasis and strong emphasis throughout a document. Prefer `*italic*` and `**bold**` for new content. * Do not put spaces inside emphasis markers: `**bold**`, not `** bold **`. * Do not use emphasis-only lines as section separators; use proper headings instead. * Avoid emphasis within words using underscores; prefer asterisks for word-internal emphasis if absolutely necessary. ## Tables * Surround tables with a blank line before and after (unless at file start/end). * Use a consistent pipe style; prefer leading and trailing pipes on all rows. * Ensure every row has the same number of cells as the header. * Keep header and delimiter rows aligned in column count so the table is recognized by renderers. * Use aligned column style: all pipe characters must align vertically across all rows. Pad cell content with spaces so pipes line up. <!-- <example-tables> --> ```markdown | Column A | Column B | Column C | |----------|----------|----------| | Short | Medium | Longer | | A | BB | CCC | ``` <!-- </example-tables> --> ## Miscellaneous * Do not include inline HTML unless necessary; if used, limit to explicitly allowed elements like `<details>` and `<summary>` in this repository. * Fenced code blocks must declare a language; use a recognized language name. If no highlighting is desired, use `text`. * Follow proper capitalization for product and technology names used in this repository (e.g., "GitHub", "JavaScript"). * Avoid using inline HTML when a Markdown equivalent exists. If an inline HTML element is necessary and allowed, keep it minimal and well-formed. * Ensure files end with exactly one trailing newline character. * Use a consistent fence marker for code blocks (backticks) across a file. * Use a consistent emphasis style throughout a file (prefer asterisks for both italic and bold). * Validate intra-document link fragments; they must match the generated IDs of headings or explicitly provided anchors. Prefer lower-case, dash-separated fragments. * When using reference-style links or images, ensure the referenced labels are defined. Remove any unused or duplicate reference definitions. Keep the special checkbox syntax `[x]` intact. * Link and image styles allowed: autolinks `<https://...>`, inline `[text](url)`, and reference `[text][label]`/`[label][]`. Avoid bare URLs in text; prefer autolink syntax. Avoid inline links where the link text equals the same absolute URL with no title; prefer autolink. * For tables, apply a consistent leading/trailing pipe style; prefer both leading and trailing pipes. Ensure all rows have the same number of cells as the header.
© microsoft · MIT · microsoft/hve-core
Similar IDE rules
All IDE rules for Writing and docs →markdown by other authors comes first.