Markdown syntax reference

This is part of the reference hub. CommonMark is the unambiguous specification of Markdown, the safe target whenever a machine, like an AI coding agent, will parse the output. Here's the core syntax.

Text and structure

Element	Syntax
Heading	# H1 ## H2 ### H3
Bold	**bold**
Italic	*italic*
Inline code	`code`
Blockquote	> quoted text
Horizontal rule	---

Links and images

Element	Syntax
Link	[label](https://example.com)
Image	

The image syntax is the one that matters for visual feedback: the alt text and surrounding prose carry meaning for text-only readers, while a vision-capable agent fetches the URL.

Lists

- bullet item
- another bullet

1. numbered item
2. next item

Code blocks

Fence with triple backticks, optionally tagging the language:

```js
const x = 1;
```

Tables

| Column A | Column B |
|----------|----------|
| cell     | cell     |

Why this is the feedback format

A coding agent reads markdown linearly and treats each heading as structure, so a review written this way becomes a clean to-do list, one task per heading. That's the whole reason CobaltCapture exports reviews as markdown. To preview how a snippet renders, use markdown preview.

Frequently asked questions

What's the difference between Markdown and CommonMark?

CommonMark is a strict, unambiguous specification of Markdown. Original Markdown left edge cases undefined, so different tools rendered the same text differently. CommonMark pins down the rules, which is why it's the safe target when a machine will parse the output.

Why does markdown matter for AI coding agents?

Markdown is the native input format for coding agents. They read it linearly and treat headings as structure. A feedback document in clean markdown becomes a parseable to-do list, where each heading is a discrete task.

How do I embed a screenshot in markdown?

Use the image syntax: an exclamation mark, alt text in square brackets, then the image URL in parentheses. A vision-capable agent fetches the URL; the alt text and surrounding prose carry the meaning for text-only readers.