К основному содержанию
правило CX Codex

markdown · microsoft — правило для Claude Code: что делает и как установить

Задаёт стандарты разметки Markdown и схемы YAML frontmatter для всех файлов .md в проекте. Помогает агенту форматировать тексты без ошибок линтера.

MIT ★ 1 627 обновлён 2026-10-25

Установить в GitHub Copilot · Вручную: положить файлы Все способы и платформы ↓
.github/instructions/markdown.instructions.md
Открыть на GitHub

Что делает markdown

Правило фиксирует требования к форматированию документов, согласованные с .markdownlint.json. Для каждого .md файла обязательно наличие YAML frontmatter в начале документа. Набор обязательных полей зависит от типа файла: для документации и корневых файлов нужны title и description, а для инструкций — description и applyTo. Даты разрешены строго в формате ISO 8601 (YYYY-MM-DD).

В разметке заголовков правило запрещает пропускать уровни и ставить знаки препинания в конце строки. Если во frontmatter уже указано поле title, основной текст обязан начинаться сразу со второго уровня ##: добавление H1 в таком случае ломает правила MD025 и MD041. Для списков стандарт предписывает маркер * и отступ в два пробела для вложенных пунктов.

Какие задачи решает

  • оформить YAML frontmatter по схемам репозитория
  • предотвратить ошибки MD025 и MD041 при наличии заголовка во frontmatter
  • привести списки и заголовки к единому стилю markdownlint
  • стандартизировать формат дат в метаданных документов

Примеры запросов агенту

  • Создай файл docs/setup.md со структурой разделов и нужным frontmatter
  • Проверь заголовки и списки в README.md на соответствие стилю markdownlint
  • Добавь метаданные с датой и кратким описанием в начало docs/api.md

Как установить markdown

Вручную: положить файлы

.github/instructions/markdown.instructions.md

Поле applyTo задаёт, к каким файлам применять

По шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать

Вопросы о markdown

Как установить markdown в Claude Code?

Создайте файл .claude/rules/markdown.md в корне проекта и сохраните в него текст этого правила.

Что делает правило markdown?

Оно синхронизирует генерацию документации с настройками .markdownlint.json, исключая конфликты уровней заголовков и пропущенные поля метаданных.

Почему нельзя использовать заголовок первого уровня при наличии поля title?

Значение title из YAML frontmatter выполняет роль названия документа, поэтому добавление # Title вызывает ошибки MD025 и MD041.

Исходный текст

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

Похожие правила IDE

Все правила IDE по теме «Тексты и документация» →

Сначала — markdown от других авторов.

markdown официальный github Правило помогает GitHub Copilot писать и проверять Markdown-файлы по CommonMark 0.31.2. Оно применяется к файлам .md. CX Codex +1 ★ 41 430звёзд репо documentation-standards pr-pm Скилл documentation-standards задаёт правила структуры документации: разделяет внутренние инструкции для контрибьюторов, пользовательские руководства в docs/ и скиллы в .claude/skills/. CX Codex +1 1установок obsidian-markdown AgriciDaniel Скилл obsidian-markdown объясняет, черновики и проверяет синтаксис Obsidian Flavored Markdown: свойства, wikilinks, вставки, callouts, теги, блоки, математику и Mermaid. CX Codex +1 593установок cmux-markdown manaflow-ai Скилл cmux-markdown для Claude Code открывает Markdown в отдельной панели рядом с терминалом и обновляет её при изменении файла. Показывает планы, заметки и документацию. CX Codex +1 7 900установок markdown-mermaid-writing K-Dense-AI Скилл markdown-mermaid-writing пишет научную документацию в Markdown и рисует структурные диаграммы Mermaid: схемы процессов, связей, таймлайны. Полезен, когда отчёт или README должны лежать в git как текст. CX Codex +1 2 300установок markdown-documentation aj-geddes Скилл markdown-documentation для Claude Code задаёт агенту правила оформления Markdown: README, вики, страницы документации. Приводит тексты, которые пишет модель, к единому виду. CX Codex +1 1 300установок verifying-markdown-formatting spencerpauly Скилл verifying-markdown-formatting проходит по Markdown-файлу чек-листом и правит форматирование: заголовки, списки, ссылки, код-блоки, пробелы. Пригодится перед коммитом README или документации. CX Codex +1 446установок

Из того же набора148

Весь набор →
Finding Deep Verifier Субагент Finding Deep Verifier для Claude Code перепроверяет находки FAIL и PARTIAL в ревью безопасности: ищет в коде доводы за и против каждой и выносит вердикт. CX Codex +1 ★ 1 627звёзд репо planner-identity-base Правило planner-identity-base для Claude Code задаёт общий каркас пошагового планирования: шесть последовательных фаз и сохранение состояния проекта в JSON. CX Codex +1 ★ 1 627звёзд репо RAI Skill Assessor Субагент RAI Skill Assessor проверяет кодовую базу или план на соответствие одному фреймворку Responsible AI. Нужен, чтобы получить структурированный список находок и рекомендаций. CX Codex +1 ★ 1 627звёзд репо rpi-walkthrough Скилл rpi-walkthrough проводит по коду, UI, UX или артефактам .copilot-tracking сегмент за сегментом, объясняя каждый блок и решение со ссылками на файлы и строки. CX Codex +1 ★ 1 627звёзд репо System Architecture Reviewer Субагент System Architecture Reviewer разбирает архитектурные решения с учётом ограничений проекта, фиксирует компромиссы и помогает сохранить обоснование решений. Пригодится перед выбором архитектуры или оформлением ADR. CX Codex +1 ★ 1 627звёзд репо Data Science and Engineering Coach Субагент Data Science and Engineering Coach, который ведёт сессию data science и инженерии данных с явным выбором задач, сохранением состояния и маршрутизацией работы в специализированные скиллы. CX Codex +1 ★ 1 627звёзд репо RAI Planner Субагент RAI Planner проводит оценку этичности и надёжности ИИ-системы по стандарту NIST AI RMF 1.0, формируя итоговый отчёт rai-plan.md через шесть фаз с проверками. CX Codex +1 ★ 1 627звёзд репо disclaimer-language Правило disclaimer-language добавляет предупреждение к планам и результатам проверок, созданным ИИ-агентом. Оно напоминает, что выводы должны пройти проверку специалиста. CX Codex +1 ★ 1 627звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой