Markdown Basics

Headings

Create headings using # symbols:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Result:

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Emphasis

*italic text*
_italic text_

**bold text**
__bold text__

***bold and italic***
___bold and italic___

Result:

italic text
italic text

bold text
bold text

bold and italic
bold and italic

Lists

Unordered Lists

- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

* Alternative bullet
* Another item

+ Another style
+ One more

Result:

• Item 1
• Item 2
  • Nested item 2.1
  • Nested item 2.2
• Item 3

• Alternative bullet
• Another item

• Another style
• One more

Ordered Lists

1. First item
2. Second item
3. Third item
   1. Nested item
   2. Another nested item
4. Fourth item

Result:

1. First item
2. Second item
3. Third item
   1. Nested item
   2. Another nested item
4. Fourth item

Links

[Link text](https://example.com)
[Link with title](https://example.com "Title text")
[Anchor link](#heading-id)

<https://example.com>
<email@example.com>

Result:

Link text
Link with title
Anchor link

https://example.com
email@example.com

Relative Links to Documentation Pages

Relative links to other markdown files are automatically rewritten to extensionless URLs:

• Extensionless: [Getting Started](/06_markdown/getting-started) → /getting-started
• Relative paths: [Installation](/guide/installation) → /guide/installation
• Auto-prefixing: Links automatically include language/version prefixes when needed
• Default language: Works correctly even when default language uses its folder

Example:

• Current file: docs/en/guide/index.md (served at /guide)
• Target file: docs/en/getting-started.md (served at /getting-started)
• Markdown: [Getting Started](/getting-started)
• Result: Automatically rewritten to /getting-started ✅

Note: Links to external URLs, anchors, and non-markdown files are left unchanged.

Images

![Alt text](/logo.png)
![Alt text with title](/logo.png "Logo title")
![Alt text](https://example.com/image.png)

Result:

Relative Image Paths

When using multi-language or versioned documentation, relative image paths are automatically handled:

• Relative paths: ./logo.png or ../images/logo.png work correctly
• Automatic rewriting: Paths are rewritten to absolute URLs when needed
• Default language: Works even when default language uses its folder (e.g., docs/en/) but URL has no prefix

Example:

• File: docs/en/index.md (served at /)
• Image: docs/en/logo.png
• Markdown: ![Logo](/06_markdown/logo.png)
• Result: Automatically resolves to /logo.png ✅

Best practices:

• Use relative paths: ./logo.png or ../images/screenshot.png
• Keep images in the same directory structure as your markdown files
• Absolute paths also work: /logo.png (from any page)

See File Structure & Organization for more details.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.

> Nested blockquote
>> Even deeper nesting

Result:

This is a blockquote.
It can span multiple lines.

And include multiple paragraphs.

Nested blockquote

Even deeper nesting

Inline Code

Use `inline code` in your text.
Use ``code with `backticks` inside`` for escaping.

Result:

Use inline code in your text.
Use code with `backticks` inside for escaping.

Code Blocks

Plain code block
with multiple lines

Result:

Plain code block
with multiple lines

Horizontal Rules

---

***

___

Result:

GitHub Flavored Markdown (GFM)

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

| Left Aligned | Center Aligned | Right Aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
| More left    | More center    | More right    |

Result:

Strikethrough

~~This text is struck through~~
~~Multiple words~~ can be struck through.

Result:

This text is struck through
Multiple words can be struck through.

Task Lists

- [x] Completed task
- [x] Another completed task
- [ ] Incomplete task
- [ ] Another incomplete task
  - [x] Nested completed task
  - [ ] Nested incomplete task

Result:

• Completed task
• Another completed task
• Incomplete task
• Another incomplete task
  • Nested completed task
  • Nested incomplete task

Autolinks

https://example.com
www.example.com
email@example.com

Result:

https://example.com
www.example.com
email@example.com

Code Blocks & Syntax Highlighting

dorcs uses Chroma for syntax highlighting with support for 200+ languages. Specify the language after the opening code fence:

package main

import "fmt"

func main() {
    fmt.Println("Hello, World!")
}

def hello_world():
    print("Hello, World!")
    return True

function helloWorld() {
    console.log("Hello, World!");
    return true;
}

#!/bin/bash
echo "Hello, World!"

name: example
version: 1.0.0
features:
  - syntax highlighting
  - multiple languages

{
  "name": "example",
  "version": "1.0.0",
  "features": ["syntax", "highlighting"]
}

<!DOCTYPE html>
<html>
<head>
    <title>Example</title>
</head>
<body>
    <h1>Hello, World!</h1>
</body>
</html>

body {
    font-family: Arial, sans-serif;
    margin: 0;
    padding: 20px;
}

SELECT name, email
FROM users
WHERE active = true
ORDER BY created_at DESC;

Result:

package main

import "fmt"

func main() {
    fmt.Println("Hello, World!")
}

def hello_world():
    print("Hello, World!")
    return True

function helloWorld() {
    console.log("Hello, World!");
    return true;
}

#!/bin/bash
echo "Hello, World!"

name: example
version: 1.0.0
features:
  - syntax highlighting
  - multiple languages

{
  "name": "example",
  "version": "1.0.0",
  "features": ["syntax", "highlighting"]
}

<!DOCTYPE html>
<html>
<head>
    <title>Example</title>
</head>
<body>
    <h1>Hello, World!</h1>
</body>
</html>

body {
    font-family: Arial, sans-serif;
    margin: 0;
    padding: 20px;
}

SELECT name, email
FROM users
WHERE active = true
ORDER BY created_at DESC;

Footnotes

Create footnotes using the footnote syntax:

Here's a sentence with a footnote[^1].

Another sentence with multiple footnotes[^2][^3].

[^1]: This is the first footnote.
[^2]: This is the second footnote.
[^3]: This is the third footnote with **bold text** and `code`.

Result:

Here’s a sentence with a footnote¹.

Another sentence with multiple footnotes²³.

HTML Support

dorcs allows embedded HTML in markdown files for advanced formatting:

<div style="text-align: center;">
  <h2>Centered Heading</h2>
</div>

<details>
  <summary>Click to expand</summary>
  This is hidden content that can be expanded.
</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd> to copy

<mark>Highlighted text</mark>

<sub>Subscript</sub> and <sup>Superscript</sup>

Result:

Ctrl + C to copy

Highlighted text

_Subscript and ^Superscript

Auto Heading IDs

All headings automatically get ID attributes based on their text, making it easy to create anchor links:

## My Section Heading

This heading automatically gets the ID my-section-heading, which you can link to:

[Link to section](#my-section-heading)

Result:

Link to section

The table of contents (TOC) is automatically generated from all headings on the page and uses these IDs for navigation.

Typographer

The typographer extension automatically converts plain text to typographically correct characters:

"Smart quotes" and 'smart quotes'
-- en dash
--- em dash
... ellipsis
(c) copyright
(r) registered
(tm) trademark

Result:

“Smart quotes” and ‘smart quotes’
– en dash
— em dash
… ellipsis
(c) copyright
(r) registered
(tm) trademark

Hard Wraps

Line breaks in markdown are preserved as hard breaks (like <br> tags), so you can format text with line breaks:

This is line one.
This is line two.
This is line three.

Result:

This is line one.
This is line two.
This is line three.

Combining Features

You can combine multiple features for rich formatting:

> **ALERT:TIP**
> Use **bold text** and `code` in alert blocks.
> 
> - Lists work too
> - Multiple items
> 
> [Links](https://example.com) are supported.

| Feature | Status | Notes |
|---------|--------|-------|
| Tables | ✅ | Fully supported |
| Code blocks | ✅ | With syntax highlighting |
| Alerts | ✅ | 5 types available |

Check out the [footnote](#footnotes) section[^example] for more details.

[^example]: This is an example footnote in a combined example.

Result:

Check out the footnote section⁴ for more details.