guides/markdown.md

Markdown

What is it

Markdown is a lightweight markup language — a way of writing plain text that renders as formatted HTML. You write in a simple, readable syntax and it becomes headings, bold text, lists, links, code blocks, and tables.

It's the standard format for README files, documentation, notes, and static site generators. Everything in this guides repo is written in Markdown. Forgejo renders it automatically when you browse a .md file.

Headings

Prefix a line with # symbols. One # is the biggest, six is the smallest.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Use headings to structure documents, not for emphasis. Don't skip levels (e.g. jumping from # straight to ###).

Emphasis

**bold text**
*italic text*
~~strikethrough~~
**bold and *italic* together**

Renders as: bold text, italic text, strikethrough, bold and italic together

Lists

Unordered

- First item
- Second item
  - Nested item (two spaces indent)
  - Another nested item
- Third item

Ordered

1. First step
2. Second step
3. Third step

Numbers don't actually have to be sequential — Markdown will render them correctly regardless. But sequential is cleaner to read in source.

Task list

- [x] Done
- [ ] Not done yet
- [ ] Also pending

Forgejo renders these as actual checkboxes.

Links and images

[link text](https://example.com)
[relative link to another file](git.md)

![alt text](https://example.com/image.png)
![local image](images/screenshot.png)

For images in a repo, put them in an images/ folder and use a relative path. Forgejo renders both remote and local images inline.

Code

Inline code

Wrap with single backticks:

Use `git status` to check your working tree.

Renders as: Use git status to check your working tree.

Code blocks

Wrap with triple backticks. Optionally specify the language for syntax highlighting:

```bash
git add .
git commit -m "Initial commit"
git push
```

```python
for i in range(10):
    print(i)
```

Forgejo and most Markdown renderers support syntax highlighting for bash, python, yaml, json, html, javascript, and many others.

Blockquotes

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

Tables

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | More     |
| Row 2    | Data     | More     |

Alignment is controlled with colons in the separator row:

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| text     | text     | text     |

Columns don't need to be perfectly aligned in source — Markdown doesn't care about spacing, only the | characters matter.

Horizontal rule

Three or more dashes on their own line:

---

Escaping

If you need to show a Markdown character literally, prefix it with \:

\*this is not italic\*
\# this is not a heading
\`this is not code\`

Line breaks and spacing

• A blank line between two blocks of text starts a new paragraph.
• A single newline in source does not create a line break in output.
• Two spaces at the end of a line forces a line break (avoid this — use a blank line instead, it's cleaner).

Frontmatter (YAML)

Some tools (Hugo, MkDocs) read metadata from a block at the top of the file:

---
title: My Guide
date: 2026-05-12
tags: [tools, reference]
---

# Content starts here

This block is not rendered as content — it's metadata for the generator. Normal Forgejo rendering ignores it.

Notes

• Markdown files use the .md extension.
• Markdown is forgiving — a mistake usually just renders oddly rather than breaking completely. When something looks wrong, check for missing blank lines or an extra space.
• Different renderers (Forgejo, GitHub, MkDocs, Hugo) are mostly compatible but have small differences. Stick to the basics in this guide and it will work everywhere.
• VS Code and most editors show a live preview of Markdown. In VS Code: Cmd+Shift+V opens the preview pane.