Skip to main content
rule CX Codex

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

Install into GitHub Copilot · Manually: put the files in place All methods and platforms ↓
.github/instructions/markdown.instructions.md
Open on GitHub

What 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.md with appropriate frontmatter fields and H2 headings
  • Align list indentation and heading markers in README.md with 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.md

The applyTo field sets which files it applies to

Step 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).

![Diagram](./diagram.png)
```
<!-- </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.

markdown official github This rule guides GitHub Copilot when it writes or reviews .md files using CommonMark 0.31.2. Its file pattern targets Markdown documents. CX Codex +1 ★ 41,430repo stars documentation-standards pr-pm documentation-standards defines repository documentation layout: keeps internal contributor docs in development/docs/, public manuals in docs/, and root files like README.md. CX Codex +1 1installs obsidian-markdown AgriciDaniel The obsidian-markdown skill explains, drafts and validates Obsidian Flavored Markdown: properties, wikilinks, embeds, callouts, tags, block references, math and Mermaid. CX Codex +1 593installs cmux-markdown manaflow-ai cmux-markdown opens Markdown files in a formatted panel beside the terminal and reloads the view when files change. Useful for plans, notes, and docs. CX Codex +1 7,900installs markdown-mermaid-writing K-Dense-AI markdown-mermaid-writing writes scientific Markdown docs and Mermaid structural diagrams: workflows, relationships, timelines, schemas. Handy when a report or README has to live in git as text. CX Codex +1 2,300installs markdown-documentation aj-geddes markdown-documentation — a skill that gives the agent a fixed set of Markdown rules for READMEs, wikis and docs pages. Useful when the model writes the text and it has to look consistent. CX Codex +1 1,300installs verifying-markdown-formatting spencerpauly verifying-markdown-formatting walks a Markdown file through a formatting checklist and fixes what it finds: headings, lists, links, code blocks, spacing. Useful before committing a README or docs. CX Codex +1 446installs

From the same set148

The whole set →
Finding Deep Verifier Finding Deep Verifier is a Claude Code subagent that re-checks FAIL and PARTIAL findings in security reviews, seeks code evidence for and against each, and rules on it. CX Codex +1 ★ 1,627repo stars planner-identity-base planner-identity-base is a Claude Code rule that provides a shared scaffold for planning agents, with six sequential phases and persistent project state in JSON. CX Codex +1 ★ 1,627repo stars RAI Skill Assessor The RAI Skill Assessor subagent checks a codebase or plan against one Responsible AI framework at a time. Use it to get structured findings and remediation guidance. CX Codex +1 ★ 1,627repo stars rpi-walkthrough rpi-walkthrough walks through code, UI, UX or .copilot-tracking artifacts segment by segment, explaining each block and decision with navigable file and line links. CX Codex +1 ★ 1,627repo stars System Architecture Reviewer The System Architecture Reviewer subagent reviews architecture choices against project constraints and records trade-offs. Use it to scope a design review or preserve the reasoning behind a decision. CX Codex +1 ★ 1,627repo stars Data Science and Engineering Coach Runs a data science and engineering coaching session with explicit job selection, persistent state, and work routed to specialized skills. CX Codex +1 ★ 1,627repo stars RAI Planner RAI Planner assesses AI solutions against NIST AI RMF 1.0 across six gated stages, generating a consolidated rai-plan.md document and tracking state. CX Codex +1 ★ 1,627repo stars disclaimer-language The disclaimer-language rule supplies caution text for AI-assisted plans and reviews. It clarifies that agent output supports human assessment rather than replacing qualified review. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open