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)

Titles (Tooltips)

You can add an optional title that appears as a tooltip when a user hovers over the element. The title is placed in quotation marks after the URL.

Syntax:

[Agpedia](https://agpedia.org "Agency Through Knowledge")

Result:

Agpedia

Reference-style Links

To keep the text clean, you can define links at the bottom of the document or section and reference them by a label.

See the [documentation][1] for more details.

[1]: https://example.com/docs "Optional Title"

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.

Simple Syntax:

| Planet  | Mass (Earths) |
| ------- | ------------- |
| Mercury | 0.055         |
| Venus   | 0.815         |
| Earth   | 1.0           |

Result:

Alignment: You can align text within columns by adding colons (:) to the header separator row. This is particularly useful for distinguishing between text descriptions, status labels, and numerical data.

• :--- : Left-aligned (best for text)
• :---: : Centered (best for status/badges)
• ---: : Right-aligned (best for numbers)

Syntax:

| Feature Description | Status | Priority Level |
| :---                | :---:  | ---:           |
| Fix rendering bug   | Open   | 10             |
| Add more citations  | Done   | 5              |

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>).

---