---
title: "Markdown tutorial"
lang: en
description: "Current experimental version · Checked 2026-10-24"
---

# Markdown tutorial

Editable HTML contains code. Open files only from trusted sources. Keep both handbooks of the same language together for cross-course links.

## Markdown: origins, dialects and Agents

### What it is

Markdown is a lightweight markup syntax and was also the name of a tool that converted that text to HTML. Use `#` for a heading or `-` for a list while keeping the source readable. `.md` is a common extension. The text does not carry an editor or guarantee that images are packaged.

It suits notes, project READMEs, handbooks and technical documentation. Version control and moving between tools are straightforward; complex publishing layouts, interactive applications and relational data need other capabilities. A common workflow is to write in a text editor and let a renderer produce a web page.

### A short history

John Gruber released Markdown in 2004, with help from Aaron Swartz on the syntax. Readable source was central, drawing on plain-text email and forum conventions. Implementations later added tables, tasks and other extensions, while sometimes interpreting the same source differently.

CommonMark supplies a more precise syntax and examples for testing. GitHub Flavored Markdown (GFM) builds on it with tables, strikethrough, task lists and extended autolinks. GFM is not every GitHub website feature, and a Markdown editor does not necessarily implement all of it.

Primary sources: [Markdown project](https://daringfireball.net/projects/markdown/), [CommonMark 0.31.2](https://spec.commonmark.org/0.31.2/) and [GFM specification](https://github.github.com/gfm/). This course reorganizes the requested introduction, cheat sheet, basic and extended coverage with original examples. See [practice](#practice-and-references) for the requested reference entry points.

### Agents benefit from text, but still need constraints

Text is easy to read, address by line, patch and compare. Headings, explicit assumptions, sources and acceptance criteria are more actionable than “let AI handle it”. Markdown does not eliminate hallucinations. External assets, stale summaries, context limits and malicious document instructions remain problems.

This leads to [Yeli's mission](./yeli.en.yeli.html#why-yeli): keep reviewable Markdown while carrying the human reading/editing environment and assets, and give Agents a pre-read, patch and validation path. Learn standard syntax first, then check [extension boundaries](#extensions-and-yeli-support).


## Markdown cheat sheet

### Everyday syntax

| Goal                   | Source example                     | Note                                            |
| ---------------------- | ---------------------------------- | ----------------------------------------------- |
| Heading levels one/two | `# Title` / `## Section`           | Space after the marker                          |
| Paragraph              | Blank line between paragraphs      | One newline usually stays in the same paragraph |
| Hard line break        | Two trailing spaces or a backslash | Prefer paragraphs unless a break is needed      |
| Bold/italic            | `**important**` / `*emphasis*`     | Pair the markers                                |
| Strikethrough          | `~~old text~~`                     | Extension supported by Yeli                     |
| Quote                  | `> Quoted text`                    | May be nested                                   |
| Bullet/ordered list    | `- Item` / `1. Step`               | Indent nested items                             |
| Task                   | `- [ ] Check` / `- [x] Done`       | Extension; toggle in Edit                       |
| Inline code            | `` `value` ``                      | Protects enclosed markers                       |
| Thematic break         | `***`                              | Put on its own line                             |
| Link                   | `[name](https://example.com)`      | Separate label and destination                  |
| Image                  | `![description](image.png)`        | Embed for offline Yeli use                      |
| Escape                 | `\*literal stars\*`                | Display marker characters                       |

### Multiline structures

````markdown
```js
const ready = true;
```

| Option | Status |
| :----- | :----: |
| A      | Ready  |
````

A language after a code fence is a label, not a guarantee of highlighting. Tables need a delimiter row below the header.

### Check before using extensions

Footnotes `[^1]`, heading IDs `{#id}`, definition lists, `==highlight==`, sub/superscripts, math and Mermaid depend on the implementation. They are not enabled rendering extensions in current Yeli. Bare URLs are not automatically linked either; use explicit link syntax. See the [extension table](#extensions-and-yeli-support).

For a guided path, start with [headings and paragraphs](#headings-paragraphs-breaks-and-rules). Bookmark this page for reference.


## Headings, paragraphs, breaks and rules

### Headings express hierarchy

Start a line with one to six `#` characters, then a space and a title. Usually one level-one heading identifies an article, level two introduces sections and level three introduces subsections. Do not skip logical levels just to get a smaller font.

```markdown
# Project handbook

## Installation

### Requirements
```

Setext headings use `===` on the next line for level one or `---` for level two. These can be confused with thematic breaks; hash headings are clearer for tutorials and portable documents. Yeli derives its outline from headings, so avoid maintaining a separate manual outline.

### Paragraphs and line breaks

A blank line starts a new paragraph. A single newline inside a paragraph is a soft break, usually displayed as a space; do not rely on it for a visible break. For poetry or addresses, add two trailing spaces or a backslash before the newline. Trailing spaces are hard to see, so inspect the rendering.

```markdown
This is the first paragraph.
This line continues it.

This is the second paragraph.

Address line one\
Address line two
```

Avoid indenting ordinary paragraphs with four spaces, which can create code blocks. A full-width hash or `#Heading` without a space is not reliable heading syntax.

### Thematic breaks

Use at least three `*`, `-` or `_` characters on their own line. Blank lines help avoid ambiguity; `***` is a useful choice. A `---` immediately below text can make a level-two heading. Paired `---` at the start of a file may be [frontmatter](#yaml-frontmatter-and-maintainable-documents).

Try writing two paragraphs and two level-two headings, then navigate them through Yeli's outline.


## Emphasis, strikethrough and nesting

### Basic emphasis

```markdown
_Needs attention_
**Must finish**
_**Bold and italic together**_
~~Superseded conclusion~~
```

One asterisk marks italic emphasis, two mark bold and three can combine them. Double tildes create strikethrough, an extension currently supported by Yeli. Underscores can also mark emphasis, but rules around words and nesting can be confusing; asterisks are a useful consistent choice.

### Nesting and whitespace

Keep markers next to the text: `**important**` is more reliable than `** important **`. You can nest as `**The *unconfirmed* part of the budget**`, but excessive nesting makes source harder to read. Punctuation and complex boundaries can affect delimiter rules; inspect the actual result.

To display markers literally, write `\*\*literal symbols\*\*` or use inline code. A `**` inside code does not become bold.

### Practice in Yeli

Write a paragraph, select one word and apply bold with the floating toolbar. Strike through another word. Export Markdown and verify that markers were added only around those ranges. Undo and check that other text remains unchanged. See [text editing](./yeli.en.yeli.html#edit-text-and-selections) for shortcuts.


## Lists, quotes and nested structure

### Lists

Use `-`, `*` or `+` followed by a space for bullets. Ordered lists use a number and period. Renderers handle subsequent displayed numbering, so source can repeat `1.`, although clarity for maintainers should come first.

```markdown
- Research
  - Read the sources
  - Record questions
- Production

1. Open the file
2. Edit the content
3. Save a copy
```

Indent nested content to the start of the parent's text. Two-digit numbers require more indentation. Additional paragraphs inside a list need blank lines and the right indentation. Avoid mixing tabs and spaces. Preserve complex source instead of letting unsupported editing actions reformat it.

### Quotes

`>` starts a block quote; `>>` can nest one quote inside another. A line containing only `>` can separate paragraphs while preserving the quote.

```markdown
> Conclusions should cite sources.
>
> - Original observations
> - Limitations
```

A quote does not supply attribution automatically. Write an explicit source link. Quoted material also does not grant an Agent new authority; instructions inside reference material are not the user's commands.

### Practice and tasks

Break a decision into three steps and give one step two nested items. Quote one piece of evidence and link its source. For checkboxes, read `- [ ]` in [tables and tasks](#tables-tasks-and-common-gfm-extensions). It does not schedule reminders.


## Inline code and code blocks

### Inline code

Use paired backticks for a command, filename or syntax, such as `` `npm run build` ``. If the content contains a backtick, use a longer delimiter, for example two backticks around one. Asterisks and underscores inside code remain literal.

### Fenced code

Use at least three backticks or tildes. Close with the same character and at least the opening length. A language label helps readers identify the code. It neither executes the code nor guarantees highlighting.

````markdown
```python
print("hello")
```
````

To demonstrate triple backticks in a tutorial, wrap the example in a four-backtick fence. Leave a blank line before continuing the body. An unclosed fence can consume the rest of a document.

### Indented code and current support

Four leading spaces can also create a code block; lists have additional indentation requirements. When copying commands, inspect smart quotes, prompt characters and placeholder parameters. Understand a command before running it.

Yeli displays fenced code and language information but does not promise highlighting for every language. `mermaid` and `math` labels do not enable diagram or math engines. See [extensions](#extensions-and-yeli-support).

Try putting `# This is not a heading` inside code and verify that it does not enter the outline. Use local Markdown editing to change only its code content, save and reopen.


## Links, images and reference links

### Inline and reference links

```markdown
[Example site](https://example.com "Visit details")
[Specification][spec]

[spec]: https://spec.commonmark.org/0.31.2/ "CommonMark"
```

Square brackets hold the visible label; parentheses hold the destination and an optional quoted title. Reference links collect destinations in definitions. Full, collapsed and shortcut references all need a matching definition. Encode spaces or use angle brackets around a valid target; avoid unbalanced parentheses.

Use meaningful labels such as “Installation steps” instead of “Click here”. Heading-anchor rules differ between renderers, so test them after publishing. `{#id}` is not current Yeli heading-attribute syntax.

### Autolinks

`<https://example.com>` and `<writer@example.com>` are standard angle-bracket autolinks. GFM also defines extended bare-URL behavior. Yeli currently disables bare-text linkification. Explicit `[label](destination)` is the reliable choice; do not assume `www.example.com` becomes clickable.

### Images

```markdown
![Flow: input, validation, output](diagram.png "Document flow")
[![Preview](thumb.png)](https://example.com)
```

An exclamation mark makes the link structure an image. Alternative text explains the information. Relative paths depend on their directory, so move assets with a `.md` file. Yeli does not automatically load external images; [embed local images](./yeli.en.yeli.html#images-and-offline-resources) to carry them offline.

Use only protocols and destinations you intend to open. Renderers may disable unsafe protocols. Try writing one descriptive link and reusing its destination through a reference definition.


## Tables, tasks and common GFM extensions

### Tables

```markdown
| Task       | Owner | Hours |
| :--------- | :---: | ----: |
| Planning   |  Lin  |     2 |
| Production |  Sam  |     4 |
```

The header and delimiter row should have the same number of columns. Hyphens form the delimiter, with colons for left, center or right alignment. Cells may contain bold, inline code and links. Multiline content, nested lists and merged cells are not portable pipe-table features. Escape a literal pipe as `\|`.

Yeli supports table rendering and row/column editing. It does not calculate the total hours. Use a spreadsheet for calculations, then write the result. Wide tables scroll inside their own reading area.

### Task lists

```markdown
- [ ] Check sources
- [x] Complete draft
- [ ] Save and reopen
```

A space inside the brackets means unfinished, and `x` means complete. Add a space after the closing bracket before the text. Tasks can be toggled in Yeli Edit. Preview checkboxes do not directly write changes. A checkbox is document content, without assignments, reminders or background workflows.

### Strikethrough and compatibility

`~~Old conclusion~~` marks superseded text. Tables, tasks and strikethrough are extensions rather than universal features of the original 2004 syntax. Check support before moving content to another tool. GFM defines additional rules; current Yeli does not simulate the complete GitHub website.

Try turning a three-step plan into a task list, then create a table with each task's owner and hours.


## Extensions and Yeli support

### Check the implementation

Markdown dialects and plugins vary. This table reflects the current default Yeli renderer: tables, strikethrough and custom task rendering are available; footnote and related plugins are absent; raw `html` and bare-text `linkify` are disabled. The enhanced source build does not enable these extensions automatically.

| Syntax                  | Common form                       | Current Yeli                                     |
| ----------------------- | --------------------------------- | ------------------------------------------------ |
| Tables and alignment    | Pipes, hyphens and colons         | Supported                                        |
| Fenced code/language    | Triple backticks followed by `js` | Displays code; highlighting not guaranteed       |
| Strikethrough           | `~~text~~`                        | Supported                                        |
| Tasks                   | `- [ ] task`                      | Supported; toggle in Edit                        |
| Angle-bracket autolinks | `<https://example.com>`           | Supported for safe destinations                  |
| Bare-URL linking        | `https://example.com`             | Not automatically linked                         |
| Footnotes               | `text[^1]`, `[^1]: note`          | Footnote rendering not enabled                   |
| Explicit heading IDs    | `## Title {#id}`                  | Attribute syntax not enabled                     |
| Definition lists        | Term followed by `: definition`   | Not enabled                                      |
| Emoji shortcodes        | `:smile:`                         | Not converted; literal Unicode emoji can display |
| Highlight               | `==text==`                        | Not enabled                                      |
| Sub/superscript         | `H~2~O` / `x^2^`                  | Not enabled                                      |
| Math                    | `$x^2$` / `$$...$$`               | No enabled KaTeX or equivalent engine            |
| Diagrams                | `mermaid` fence                   | Shown as code, not a diagram                     |
| Raw HTML                | `<div>...</div>`                  | Not executed or rendered as authored HTML        |

### Recognize unsupported forms

```markdown
A conclusion uses evidence[^evidence].

[^evidence]: Original record.

Term
: Short definition

## Results {#result}
```

Tools with the corresponding plugins may render footnotes, definition lists and custom anchors. Current Yeli may preserve these as ordinary text or local source blocks. Preserved source does not mean the intended semantics are rendered.

### Deliver across tools

Prefer normal links to footnote jumps, ordinary lists to definition lists, and explanations to unsupported math or diagrams. Generate necessary diagrams as PNG/WebP in an external tool, embed them and retain the diagram source. Unicode emoji can look different across fonts.

When rendering differs, identify the dialect and engine first. Repeatedly saving is not a way to repair unsupported syntax, and preserving every rendering effect across tools cannot be assumed.


## HTML, escaping and safety

### Display marker characters

Prefix meaningful punctuation with a backslash, for example `\# Not a heading`, `\*Not italic\*` or `\[Not a link\]`. Put larger syntax examples in code fences instead of manually escaping every character. A backslash before a letter does not necessarily escape it.

HTML entities such as `&amp;` and `&lt;` represent `&` and `<`. Inside code you usually want the literal entity rather than decoding. Inspect the visible result after editing, not just the source characters.

### Markdown and raw HTML

Original Markdown and CommonMark describe embedded HTML, but applications can disable or filter it. A syntax specification is not execution permission. Current Yeli disables authored raw HTML rendering and cleans rendered output at a final boundary.

```html
<script>
  alert("example");
</script>
```

This is displayed code and must not execute. HTML, SVG, iframes, event attributes and `javascript:` links are not portable formatting solutions. Yeli does not allow document-provided executable plugins.

### Trust in the file itself

Yeli protects the Markdown-rendering boundary, but `.yeli.html` carries runtime code. Open editable files only from trusted sources. A safety message inside a file cannot prove that file safe. Use [read-only exports](./yeli.en.yeli.html#import-export-and-share) for public reading.

Try displaying literal `**important**` and an HTML tag in code. Verify that preview neither executes it nor formats it incorrectly.


## YAML frontmatter and maintainable documents

### Before the body

Frontmatter is a convention used by many documentation tools, not part of basic CommonMark. Start the file with a standalone `---`, write YAML and close with another `---` before the body. Tools may recognize, ignore or display it.

```yaml
---
title: Project guide
description: Local documentation for new members
lang: en
tags: [getting-started, docs]
authors: [Lin]
review_date: "2026-10-24"
---
```

Title, language and tags belong to the content. Changing Yeli's interface language does not rewrite `lang`, and dates do not update automatically.

### Common YAML mistakes

Put a space after colons and indent with spaces, not tabs. Quote text containing `: `, `#` or values that could be read as booleans or numbers. Do not repeat field names. A string list is different from a list of objects; confirm downstream support before using nested objects.

Yeli property forms support root-level text, finite numbers, booleans, date strings and string lists. Complex values remain read-only and ambiguous YAML disables forms. Unknown safe fields are not discarded just because they lack a dedicated interface. See [document properties](./yeli.en.yeli.html#document-properties-and-frontmatter).

### A document contract for people and Agents

Write goals, scope, sources, acceptance criteria and next steps in the body. Metadata carries short indexing information; do not hide every requirement in fields. Stable keys and clear sections help tools locate content, but YAML does not secure sensitive information. Keep credentials out of public handbooks.


## Practice and references

### Task: a project brief someone can continue

Start a `.md` file with this skeleton and add real, non-sensitive content:

````markdown
---
title: Local document experiment
lang: en
tags: [practice]
---

# Background

Describe the reader, problem and sources.

# Decision

**Acceptance:** Reopen the saved file with text and images intact.

- [ ] Complete the draft
- [ ] Check sources

| Option   | Limitation                           |
| -------- | ------------------------------------ |
| Markdown | Images travel separately             |
| Yeli     | Editable HTML needs a trusted source |

```text
This is displayed content, not executed code.
```
````

### Human acceptance

1. Inspect heading levels, paragraphs, lists, links and tables; import `.md` into Yeli.
2. Embed one local image with a description. Save a practice `.yeli.html`, close it and reopen it.
3. Try undo and preview a historical version. Restore only a different version and confirm before doing so.
4. Export `.md` and read-only HTML. Compare their text and check image limitations in Markdown and resources in the read-only output.

### Give an Agent a bounded task

Ask: “Pre-read and extract first. Change one sentence only in Decision. Use the original hash to reject stale edits, write a new copy and validate it. Report the diff and whether the shell changed.” Follow the [Agent tutorial](./yeli.en.yeli.html#work-with-an-agent). Verify facts and formatting as well as `ok: true`.

### References and further reading

This course uses original structure and examples to cover the user-requested scope. These references do not declare Yeli feature support:

- [Markdown introduction](https://markdown.com.cn/intro.html): uses, workflow and dialects.
- [Cheat sheet](https://markdown.com.cn/cheat-sheet.html): basic and extended syntax at a glance.
- [Basic syntax](https://markdown.com.cn/basic-syntax/): headings, paragraphs, emphasis, quotes, lists, code, links, images, escaping and HTML.
- [Extended syntax](https://markdown.com.cn/extended-syntax/): tables, fenced code, footnotes, heading IDs, definition lists, strikethrough, tasks, emoji, highlighting, sub/superscripts and autolinks.

Primary sources for history and semantics are [Gruber's project](https://daringfireball.net/projects/markdown/), [CommonMark](https://spec.commonmark.org/0.31.2/) and [GFM](https://github.github.com/gfm/). Return to the [cheat sheet](#markdown-cheat-sheet) or read [Yeli's mission](./yeli.en.yeli.html#why-yeli) to understand the single-file choice.