docs: massive doc update

site/docs/markdown.md

@@ -0,0 +1,41 @@
+---
+title = "Markdown Extensions"
+---
+# Markdown Extensions
+
+## Directory Index Customisation
+
+By default, directories without an `index.md` get an auto-generated index page listing their contents.
+
+If you create your own `index.md` in a directory, you can still include the auto-generated file list by using the `{{LIST}}` placeholder:
+
+```md
+# Blog
+
+This is my blog. The posts are below. The top-most one is the most recent.
+
+{{LIST}}
+```
+The `{{LIST}}` placeholder is replaced with the autogenerated file list.
+
+## Table of Contents
+
+`{{TOC}}` auto-generates a nested heading list with clickable anchors.
+
+## Footnotes
+
+Full support for `[^id]` footnotes and `[^id]: text` definitions. They render as a numbered `<section>` at the bottom of the page.
+
+## Definition Lists
+
+Definition lists use the standard syntax:
+
+```md
+Term
+: Definition
+```
+This renders as `<dl><dt>Term</dt><dd>Definition</dd></dl>`. Multiple definitions per term are supported.
+
+## Emoji Shortcodes
+
+Standard GitHub/MkDocs emoji shortcodes like `:smile:`, `:fire:`, `:rocket:` are automatically replaced with their Unicode emoji equivalents. Shortcodes inside code blocks are left as-is.