markdown · microsoft — правило для Claude Code: что делает и как установить
Задаёт стандарты разметки Markdown и схемы YAML frontmatter для всех файлов .md в проекте. Помогает агенту форматировать тексты без ошибок линтера.
MIT ★ 1 627 обновлён 2026-10-25
.github/instructions/markdown.instructions.mdЧто делает 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 задаёт, к каким файлам применять
Вручную: положить файлы
.claude/rules/markdown.mdПоле paths во frontmatter ограничивает файлы: applyTo из источника → paths
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/markdown.mdcВо frontmatter: description, globs, alwaysApply. applyTo из источника → globs, иначе правило само не подключится
Вручную: положить файлы
.devin/rules/markdown.mdВручную: положить файлы
.clinerules/markdown.mdПо шагам, с командами для каждой платформы: 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).  ``` <!-- </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 от других авторов.