LLM Best Practices

Markdown Syntax Cheatsheet

Last updated 2 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Markdown is a family of dialects, so pick the syntax by the target renderer: writing [[wikilink]] in a GitHub README renders literally. This site uses Obsidian-flavored Markdown through quartz.

Support by dialect

Target the dialect your renderer uses; stay with CommonMark features when unsure.

FeatureCommonMarkGitHubObsidianMDX
Headings, lists, code fences, quotes, links, imagesyesyesyesyes
Indented code blocksyesyesyesno
Raw HTML (<br>)yesyesyesno, JSX only: <br />
Tables, task lists, ~~strikethrough~~noyesyeswith remark-gfm
Footnotes [^1]noyesyeswith remark-gfm
Math $x^2$, $$...$$noyesyeswith a math plugin
Callouts > [!NOTE]noyes (alerts)yeswith a plugin
Wikilinks [[page]]nonoyeswith a plugin
JSX componentsnononoyes

Core syntax

Use these in every dialect.

# Heading        *emphasis*   **strong**   `code`
[text](url)      ![alt](url)  &copy;
- item            1. item      > quote   ---

Task lists (- [ ]) and strikethrough need GitHub, Obsidian, or MDX with remark-gfm; see the table above. Angle-bracket autolinks (<https://example.com>) work in CommonMark, GitHub, and Obsidian but not in MDX, where < starts JSX.

Syntax

Copy these snippets for tables, footnotes, callouts, and wikilinks.

| Left | Center | Right |
| :--- | :----: | ----: |
| a    |   b    |     c |
 
Text with a footnote.[^1]
 
[^1]: The footnote text.
 
> [!NOTE]
> 
> GitHub alerts: NOTE, TIP, IMPORTANT, WARNING, CAUTION.
 
[[slug]]   [[folder/slug|Display text]]   [[slug#section|Section]]

Obsidian callouts add many more types (info, success, question, failure, danger, bug, example, quote). Frontmatter is a YAML block between --- lines at the top of the file; static-site generators read it, and GitHub shows it as a table in rendered .md files.

MDX

Close every tag, and avoid indented code in MDX.

import Note from "./Note"
 
<Note variant="warning">A React component inline.</Note>

MDX treats everything indented as JSX, so indented code blocks do not exist, and every tag must close (<br />).

Gotchas

Avoid these; each breaks rendering silently.

GotchaFix
Blocks need a blank line between them, and a table needs one before its first row.Add the blank line.
Two trailing spaces force a hard break but are invisible in review.End the line with \, or start a new paragraph.
Tables cannot hold multi-line cells.Use <br> (not in MDX) inside the cell.
Wikilinks render as literal text outside Obsidian and Quartz.Use [text](path) in files GitHub renders.
Fences must open and close with the same character (``` or ~~~).Match them.
A literal dollar sign can start math.Escape it as \$.

Backlinks