Markdown how-to

Markdown is a lightweight markup language designed for creating formatted text using a plain-text editor. Created by John Gruber and Aaron Swartz in 2004, its primary goal is readability: the source document should be as legible as possible in its unrendered form ^[1].

Today, Markdown is the standard for documentation, technical writing, and web-based communication. Because the original specification left some behaviors undefined ^[2], various "flavors" (dialects) have emerged, most notably CommonMark (a highly standardized version) ^[3] and GitHub Flavored Markdown (GFM) ^[4].

Core Syntax

The following elements are widely supported across almost all Markdown parsers and form the foundation of the language.

Headings

Headings are created by prefixing text with hash symbols (#). The number of hashes corresponds to the heading level (1 through 6).

# Level 1 Heading
## Level 2 Heading
### Level 3 Heading

Emphasis

Text can be styled as italics or bold using asterisks (*) or underscores (_).

Lists

Unordered lists use asterisks, pluses, or hyphens. Ordered lists use numbers followed by a period.

- Item 1
- Item 2
  - Nested Item (indent with 2 or 4 spaces)

1. First item
2. Second item

Note: In most implementations, the actual numbers used in an ordered list do not matter; the parser will automatically increment them.

Links and Images

Links and images share a similar bracketed syntax.

• Link: [Agpedia](https://agpedia.org)
• Image: ![Alt text for accessibility](https://example.com/image.png)

Blockquotes

Blockquotes are indicated by the > symbol at the start of a line.

> "Simplicity is the ultimate sophistication."
> — Leonardo da Vinci

Code

Inline code is wrapped in single backticks (`). Block code is typically indented by four spaces or, in more modern implementations, wrapped in "fences" of three backticks (```).

Extensions and GitHub Flavored Markdown

Many platforms, including GitHub, add features to the core specification to support technical and collaborative workflows.

Tables

Tables are constructed using pipes (|) and hyphens (-). Hyphens define the header row, and colons within the header separator can be used for alignment.

Syntax:

| Feature | Support | Description |
| :--- | :---: | ---: |
| Tables | GFM | Left, center, and right aligned |

Result:

Task Lists

Task lists allow for the creation of interactive or visual checklists.

Syntax:

- [x] Complete the draft
- [ ] Review for clarity
- [ ] Add citations

Result:

• [x] Complete the draft
• [ ] Review for clarity
• [ ] Add citations

Strikethrough

Double tildes are used to indicate deleted or corrected text.

Syntax:

This is ~~wrong~~ corrected.

Result:

This is wrong corrected.

Autolinks

GFM and many modern parsers automatically convert URLs and email addresses into clickable links without requiring special Markdown syntax.

https://example.com

Structural Rules

Paragraphs and Line Breaks

• Paragraphs: Created by separating lines of text with one or more blank lines.
• Hard Line Breaks: To force a line break within a paragraph, end a line with two or more spaces, or use a backslash (\) at the end of the line.

Horizontal Rules

Three or more hyphens, asterisks, or underscores on a line by themselves create a thematic break (<hr>).

---