feat: might be actually feature-complete by now

site/Docs/configuration.md

@@ -15,11 +15,13 @@ You can set metadata for a page using a `site.conf`-style frontmatter block at t
 title = "Custom Page Title"
 date = "2026-03-23 11:32"
 draft = false
+description = "A short page summary"
 ---
 ```
 - `title` - overrides the page title, post name in index links, and RSS `<title>`.
 - `date` - overrides the post date and time. Supports `YYYY-MM-DD` and `YYYY-MM-DD HH:MM` (or `HH-MM`).
 - `draft` - if `true`, the file is excluded from HTML generation.
+- `description` - page description, used for Open Graph `og:description` meta tag.
 
 ## Directory Index Customisation
 
@@ -34,4 +36,26 @@ This is my blog. The posts are below. The top-most one is the most recent.
 
 {{LIST}}
 ```
-The `{{LIST}}` tag will be replaced with the generated list of links to child pages and files, exactly as in case the custom index didn't exist.
+The `{{LIST}}` tag will be replaced with the generated list of links to child pages and files, exactly as in case the custom index didn't exist.
+
+## Table of Contents
+
+You can auto-generate a Table of Contents by placing `{{TOC}}` anywhere in your markdown file. It collects all `h2` and `h3` headings and generates an ordered list with anchor links.
+
+## Footnotes
+
+Footnotes use the `[^id]` syntax inline and `[^id]: text` for definitions at the bottom of the file. They are rendered as a numbered `<section>` at the end 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.

site/Docs/usage.md

@@ -9,11 +9,15 @@ kewt --generate-template [path]
 kewt --update [dir]
 kewt --from <src> --to <out>
 kewt [src] [out]
+kewt --watch
+kewt --serve [port]
 ```
 - `--new [title]` creates a new site directory with a default `site.conf`, `template.html`, and `index.md`.
 - `--post [title]` creates a new markdown file in the configured `posts_dir` with the current date/time as the filename and default frontmatter.
 - `--generate-template [path]` writes the default `template.html` to the given path (defaults to `template.html` in the current directory).
 - `--update [dir]` adds any missing keys to `site.conf` and checks `template.html` against the latest default.
+- `--watch` (`-w`) watches for file changes in the source directory and rebuilds automatically.
+- `--serve` (`-s`) starts a local HTTP server (python3 or busybox) in the output directory after building. Use with the port number to specify the port. Composable with `--watch`.
 
 ## site.conf
 
@@ -42,6 +46,7 @@ base_url = ""
 generate_feed = false
 feed_file = "rss.xml"
 posts_dir = ""
+posts_per_page = 12
 custom_admonitions = ""
 ```
 - `title` - site title
@@ -67,5 +72,6 @@ custom_admonitions = ""
 - `generate_feed` - enable RSS feed generation (requires `base_url`)
 - `feed_file` - filename for the generated RSS feed (default: "rss.xml")
 - `posts_dir` - directory name containing posts (e.g., "posts"). Enables reverse-chronological sorting, title headings in indexes, and automatic backlinks.
+- `posts_per_page` - number of posts per page in paginated post indexes (default: 12). Set to 0 to disable pagination.
 - `enable_header_links` - turns markdown section headings into clickable anchor links (default: true)
 - `custom_admonitions` - comma separated list of custom admonitions