| applyTo | **/*.md |
|---|
Four audiences read Markdown files in this repository:
- Humans
- AI models
- Developer tools (linters, parsers, extractors)
- IDEs, terminals, and other display environments
Each audience parses structure differently. Humans rely on visual cues. The other three rely on Markdown syntax elements.
Common examples of this asymmetry:
- Bold text that looks like a heading to a human is still just emphasized text to every other reader.
- A nested list that looks organized to a human is an ambiguous structure that tools and AI models cannot reliably interpret.
- Nested code blocks can be understood by LLMs but break display for humans and cannot be parsed by tools.
- Emojis and other Unicode characters can be visually distinctive but are invisible noise to tools and AI models, besides potential issues in some display environments.
Use only Markdown elements that carry structural meaning in the syntax itself. If a formatting choice depends on visual appearance to convey its purpose, it will fail for three out of four audiences. When this file does not cover a specific case, apply this principle to decide.
All meaning must reside in words and sentence structure. If removing a formatting element (bold, dash, nesting, indentation) would change what the text says, that meaning is encoded in a layer that three audiences cannot access. Express relationships through explicit words and punctuation instead: a colon to introduce an explanation, a semicolon to connect related clauses, or a separate sentence when the original phrasing carried a causal or conditional relationship.
When restructuring existing text to follow these rules, preserve all original meaning and detail; changing the format must not change the content.
A well-formed file is more than a set of clean items. The order and nesting of its sections carry meaning of their own, and that arrangement is the first thing a reader uses to make sense of the file. Organize the content into sections and subsections, each under its own heading with paragraphs inside, and reach for a list, table, or code block only where it organizes the information better than prose would.
Readers rarely consume a long file top to bottom. Humans scan, and AI models often read only part of a file, so the most important information should sit near the top where a quick glance can reach it. Aim for an outline that tells the story on its own: reading only the headings should reveal what the file holds and where its key points are.
- Organize the file into sections and subsections, each under its own heading with paragraphs inside.
- Order sections so the most important information comes first, because long files are rarely read in full.
- Make the heading outline readable on its own, so a scan of the headings reveals the structure and the key points.
- Use a list, table, or code block only where it organizes the content better than prose.
- Lead each section with its main point, so a reader who stops early still gets it.
AI-drafted prose has recognizable tells: filler words, hedging, and sentences built on a false opposition such as "it is not just X, it is Y". These constructions pad the text and bury the point under words that carry no meaning.
When you see that pattern in a draft, stop and ask what the paragraph is for: the one thing it needs to say, then say that in plain words. Keep the important details and the nuances of meaning; simplify by default, but never drop substance to do it. The target is prose that is clear and easy to follow on the first read, for humans and models alike.
- Cut filler words and hedging that do not change the meaning.
- Do not build a sentence on a false opposition when a plain statement says it better.
- When a sentence reads like AI prose, restate the paragraph's goal in plain words and keep that version.
- Preserve the original details and nuances of meaning; simplify the wording, not the substance.
- Write so the point lands on the first read, without rereading.
Headings are the only Markdown element that all four audiences interpret as structure. IDEs and editors build an automated document outline from heading levels, and humans use that outline to jump between sections and navigate large files quickly. Document navigation, breadcrumbs, and AI section-boundary detection depend on the same heading syntax. Bold text, regardless of how prominent it looks, appears in none of these, so a skipped or faked heading silently removes a section from every reader that relies on the outline.
- Use
#(ATX) syntax only, not underline-style (Setext). - Use exactly one h1 per file as the document title.
- Do not skip levels. An h4 must appear under an h3, not directly under an h2.
- Use h1 through h6 as needed. Do not artificially stop at h3: if the information structure implies deeper nesting, use heading levels accordingly (up to h6).
- Never use bold text as a substitute for a heading.
- When you need finer structure than your current deepest heading, use the next heading level.
A list item should hold a single idea. "Atomic" here does not mean literally indivisible; it means that splitting the item further would not make its content any clearer in this context. Some items could be divided but read better whole, and that is fine. When an item instead carries a sub-list, a bold label with content, or several separate points, tools and AI models cannot reliably tell where one item's meaning ends and the next begins. The real signal is overload, not length: if an item only fits by hanging a sub-list under it, the content has outgrown the list form, and since nested lists are hard to read, promote that structure to sections with their own headings.
A list item that reads as a full paragraph, or that runs to several sentences, is the clearest flag to rewrite. At that size the list is no longer presenting the information properly, and the content belongs in prose or in its own section.
- Do not nest lists. Promote the nested structure to a section with its own heading.
- Do not use the bold-label pattern (
- **{label}:** {content}). Convert it to a heading with prose underneath for better document structure and readability. - Keep each item to a single idea, and split it further only where that makes the content clearer.
- Rewrite any item that reads as a paragraph or runs to several sentences; move it to prose or its own section.
- Use
-for unordered lists, numbers for ordered.
Bold and italic do not function as importance signals outside of human visual scanning on properly rendered UIs (a terminal shows the raw asterisks, which reduces readability). AI models do not treat bold text as higher priority, and developer tools ignore emphasis entirely when analyzing document structure. Any priority conveyed only through emphasis is therefore lost for three of the four audiences.
Inline code with backticks is the right tool for a real code token, a file path, or a command, but agents tend to overuse it. Wrapping ordinary words in backticks adds noise, and a long inline span can be pushed onto its own line by some editors, which breaks the sentence. Reserve it for text that is literally code.
- Do not use bold or italic to signal importance or priority.
- Use backticks only for real code tokens: identifiers, file paths, and commands.
- Do not wrap ordinary prose or emphasis words in backticks.
- Keep an inline code span short. If it runs long, use a fenced block or a separate file instead.
- Communicate importance through position and word choice such as must, never, and always.
- If content must stand out, give it its own heading.
Terminals and many display environments render only a limited character set reliably. A byte sequence outside ASCII can appear as garbled placeholder glyphs, an effect called mojibake, which is visual noise for humans and produces unreadable or misleading tokens for agents parsing the raw file. Restricting the file to ASCII keeps it legible and parseable everywhere it is opened.
Non-ASCII characters are also easy to introduce by accident. Smart quotes, typographic dashes, arrow glyphs, and the ellipsis character often arrive through copy-paste, look almost identical to their ASCII equivalents, yet parse and display differently. Arrows in particular render badly in the terminal, so write -> rather than the arrow glyph.
- Use plain ASCII for all structural, punctuation, and formatting characters.
- Replace curly or smart quotes with straight ASCII quotes.
- Replace typographic dashes and the ellipsis character with their ASCII equivalents.
- Replace arrow glyphs with an ASCII form such as
->. - Do not use emojis or decorative Unicode symbols.
- Keep non-ASCII characters only when they carry content meaning that cannot be expressed otherwise, such as a person's name or a quoted foreign term, because removing them would change what the text says.
Em dashes deserve their own note because they are both a style problem and an encoding problem. They are a recognizable AI writing pattern that lowers the perceived quality of the text, and being non-ASCII they break in the terminal along with the characters above. In careful English the em dash is almost never the right choice; the sentence is easier to read once it is rewritten.
The em dash is most often used to drop one clause inside another as a parenthetical insert. That insertion interrupts the main clause and forces the reader to hold it in memory, which hurts both readability and the message. Prefer to rewrite: split the sentence, move the aside into round brackets, or set it off with commas.
- Do not use em dashes as punctuation.
- Do not use double hyphens as punctuation.
- Rewrite the sentence for clarity instead of inserting a clause between em dashes.
- Use a period to split into two sentences.
- Use a semicolon for closely related clauses.
- Use a colon to introduce an explanation.
- Use round brackets for a genuine aside.
Multiple Markdown parsers interpret --- as a YAML frontmatter delimiter. In the body of a document it can silently truncate content, produce parsing errors, or break document-splitting tools, so a separator that looks harmless to a human can corrupt the file for tools.
YAML frontmatter is allowed when it is intended. It must appear only at the very start of the file.
- Allow YAML frontmatter blocks only at the start of a file. Use the pattern
---on the first line, YAML key-value pairs, then---to close. - Never use horizontal rules (
---,***,___) in the body of a Markdown document. - Use headings to create section boundaries.
A language identifier does more than enable syntax highlighting. Many IDEs parse the block as real code in that language and report warnings or errors, so a snippet that is not self-contained produces noise that has nothing to do with the document. Tagging a block with a language is a promise that the code is valid and complete on its own.
When a complete example does not fit, put the real code in its own file and link to it from the prose, so the example stays runnable and testable. Use a text-tagged block only as a last resort, for a fragment that cannot be made standalone and cannot live in a separate file. It renders the same but is not inspected.
- Never leave a fence bare; every fenced block carries an identifier.
- Use the real language tag only for a complete, self-contained example the reader can run as-is.
- When the code cannot be self-contained, move it to its own file and link to that file from the prose.
- Use the
texttag for a fragment that cannot be made standalone, to avoid IDE inspection noise. - Keep examples minimal. Use the shortest code that demonstrates the point.
- Show commands the reader should run, not terminal session transcripts.
- Do not nest code blocks inside one another.
Tables work reliably across all four audiences when kept simple. Parsers struggle with complex content in cells, and wide or richly formatted tables break in narrow windows and in the terminal, so complexity in a table degrades the file for the readers that cannot lay it out visually.
- Always include a header row.
- Keep cell content to short phrases.
- Do not place headings, lists, or code blocks inside cells.
- Promote complex cell content to its own section.
- Do not use bold or italic text as a marker for table headers. Use the header row for this purpose.
- Do not hand-pad columns to align them; the alignment breaks in narrow windows and in the terminal.
Short paragraphs are easier to skim and easier for tools and AI models to segment into coherent units. Placing the most important information first means a reader or model that stops early still captures the point.
- Write one to three sentences per paragraph.
- Express one idea per paragraph.
- Place the most important information in the first sentence.
- When a paragraph grows beyond three or four sentences or contains separate ideas, split it or promote the content to its own headed section.
Write each paragraph as one physical line and let the editor soft-wrap it on screen. Do not hard-wrap prose at a fixed column. Hard wrapping splits a single idea across many lines, so editing one word reflows the whole block and the git diff then shows many changed lines instead of one. That noise hides the real change in review and creates avoidable merge conflicts.
Separate blocks with exactly one blank line. The blank line is the delimiter that tells every parser where one paragraph, heading, list, or code block ends and the next begins. Without it, adjacent blocks merge or render incorrectly, and a list placed directly under a paragraph may not be recognized as a list.
- Write each paragraph on a single line with no hard line breaks inside it.
- Rely on the editor's soft wrap for on-screen width, not on inserted line breaks.
- Put exactly one blank line between every block, including between a paragraph and a following list or heading.
- Keep each list item on its own single line, without hard breaks inside the item.
- Markdown syntax documentation: https://www.markdownguide.org/basic-syntax/ for reference on how different Markdown elements are rendered and parsed.