4.4 KiB
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
The same formatting can also be written with underscores:
_italic_
__bold__
__bold and _italic_ together__
* and _ are interchangeable. Convention is to use * for italic and **
for bold — reserve _ for nesting to avoid ambiguity.
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)
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
.mdextension. - 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+Vopens the preview pane.