Markdown Reference

Markdown and GitHub Flavored Markdown. When to use Markdown vs AsciiDoc, GFM extensions, and syntax reference.

When Markdown (Not AsciiDoc)

Markdown remains the right choice for:

README.md files — GitHub/GitLab renders natively
CLAUDE.md, MEMORY.md — Claude Code expects Markdown
CHANGELOG.md — conventional changelog tooling assumes Markdown
GitHub Issues and Pull Request descriptions
Quick notes that never enter Antora

For anything published through Antora, use AsciiDoc.

Headings and Text

Headings (ATX style)

# H1 -- document title
## H2 -- major section
### H3 -- subsection
#### H4 -- detail

Inline formatting

**bold**  *italic*  `monospace`  ***bold italic***
~~strikethrough~~  [link text](url)  ![alt](image.png)

Lists

Unordered and ordered lists

- Item one
  - Nested item
    - Third level

1. First step
   1. Sub-step
2. Second step

Task lists (GFM extension)

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

GitHub renders these as interactive checkboxes in Issues and PRs.

Code Blocks

Fenced code block with language hint

```bash
awk -F: '{print $1, $3}' /etc/passwd
```

Inline code

Use `grep -r` to search recursively.

Tables

GFM table with alignment

| Left   | Center  | Right |
|:-------|:-------:|------:|
| data   | data    | data  |
| more   | more    | more  |

Colons control alignment: :--- left, :---: center, ---: right.

Links and Images

Links and references

[inline link](https://example.com)
[reference link][ref-id]
[relative link](./docs/page.md)

[ref-id]: https://example.com "Title"

Images with alt text

![Architecture Diagram](images/arch.png)
![Badge](https://img.shields.io/badge/status-active-green)

Blockquotes and Admonitions

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquote.

GitHub-flavored admonitions (GFM)

> [!NOTE]
> Informational aside.

> [!WARNING]
> Potential problem ahead.

> [!TIP]
> Helpful suggestion.

> [!IMPORTANT]
> Key requirement.

> [!CAUTION]
> Data loss risk.

Footnotes

Footnote syntax (GFM)

This needs clarification[^1].

[^1]: Here is the footnote content.

AsciiDoc vs Markdown Quick Comparison

Feature Markdown AsciiDoc

Feature	Markdown	AsciiDoc
Bold	`text`	`text`
Code block	```bash	`[source,bash]` + `----`
Link	`[text](url)`	`text`
Image	`![alt](path)`	`image::path[alt]`
Table cell content	Plain text only	AsciiDoc markup (lists, code)
Includes	None	`include::path[]`
Cross-references	Relative links	`xref:page.adoc[text]`
Admonitions	GFM `> [!NOTE]`	Native `NOTE:` or block `[NOTE]====`
Conditionals	None	`ifdef`, `ifndef`
Attributes/variables	None	`{attribute-name}`

Bold

text

Code block

```bash

[source,bash] + ----

Link

[text](url)

text

Image

![alt](path)

image::path[alt]

Table cell content

Plain text only

AsciiDoc markup (lists, code)

Includes

None

include::path[]

Cross-references

Relative links

xref:page.adoc[text]

Admonitions

GFM > [!NOTE]

Native NOTE: or block [NOTE]====

Conditionals

None

ifdef, ifndef

Attributes/variables

None

{attribute-name}

The comparison is not "which is better" — it is "which context demands which tool." GitHub context: Markdown. Antora publishing: AsciiDoc.