From 8fba174a6e057acafaafa54e8ef44476f060c8c3 Mon Sep 17 00:00:00 2001
From: Einar <me@ege.cx>
Date: Tue, 12 May 2026 16:53:12 +0200
Subject: [PATCH] Add Markdown reference guide and update README

---
 README.md   |   1 +
 markdown.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 199 insertions(+)
 create mode 100644 markdown.md

diff --git a/README.md b/README.md
index 48eab59..d152f64 100644
--- a/README.md
+++ b/README.md
@@ -5,4 +5,5 @@ Personal reference docs for tools I use regularly.
 ## Tools
 
 - [git](git.md) — Version control. Tracking changes, committing, pushing to Forgejo, undoing mistakes.
+- [markdown](markdown.md) — Lightweight markup language for formatting plain text. Headings, lists, code blocks, tables, and more.
 - [rclone](rclone.md) — File syncing and copying between local storage and remote destinations. SFTP, object storage, and 60+ backends.
diff --git a/markdown.md b/markdown.md
new file mode 100644
index 0000000..3309e85
--- /dev/null
+++ b/markdown.md
@@ -0,0 +1,198 @@
+# 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**
+
+## 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)
+
+![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:
+
+```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.