209 lines
4.4 KiB
Markdown
209 lines
4.4 KiB
Markdown
# 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.
|
|
|
|
```markdown
|
|
# 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
|
|
|
|
```markdown
|
|
**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:
|
|
|
|
```markdown
|
|
_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
|
|
|
|
```markdown
|
|
- First item
|
|
- Second item
|
|
- Nested item (two spaces indent)
|
|
- Another nested item
|
|
- Third item
|
|
```
|
|
|
|
### Ordered
|
|
|
|
```markdown
|
|
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
|
|
|
|
```markdown
|
|
- [x] Done
|
|
- [ ] Not done yet
|
|
- [ ] Also pending
|
|
```
|
|
|
|
Forgejo renders these as actual checkboxes.
|
|
|
|
## Links and images
|
|
|
|
```markdown
|
|
[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:
|
|
|
|
```markdown
|
|
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:
|
|
|
|
````markdown
|
|
```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
|
|
|
|
```markdown
|
|
> This is a blockquote.
|
|
> It can span multiple lines.
|
|
>
|
|
> And multiple paragraphs.
|
|
```
|
|
|
|
## Tables
|
|
|
|
```markdown
|
|
| Column 1 | Column 2 | Column 3 |
|
|
|----------|----------|----------|
|
|
| Row 1 | Data | More |
|
|
| Row 2 | Data | More |
|
|
```
|
|
|
|
Alignment is controlled with colons in the separator row:
|
|
|
|
```markdown
|
|
| 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:
|
|
|
|
```markdown
|
|
---
|
|
```
|
|
|
|
## Escaping
|
|
|
|
If you need to show a Markdown character literally, prefix it with `\`:
|
|
|
|
```markdown
|
|
\*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:
|
|
|
|
```markdown
|
|
---
|
|
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.
|