From 93fd0e02ad4442e14cbe1357325e0bc8137a733f Mon Sep 17 00:00:00 2001
From: haskal <haskal@awoo.systems>
Date: Tue, 8 Jun 2021 01:20:14 -0400
Subject: [PATCH] briefly document the markdown extensions

---
 defs.rkt          |  1 +
 doc/extensions.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 doc/extensions.md

diff --git a/defs.rkt b/defs.rkt
index b2ada9f..7affdec 100644
--- a/defs.rkt
+++ b/defs.rkt
@@ -9,6 +9,7 @@
             (list/c 'date integer? integer? integer?)
             (list/c 'title string?)
             (list/c 'slug string?)
+            (cons/c 'tags (listof string?))
             (list/c 'summary string?)
             (cons/c 'authors (listof string?)))))
 
diff --git a/doc/extensions.md b/doc/extensions.md
new file mode 100644
index 0000000..63b1cdb
--- /dev/null
+++ b/doc/extensions.md
@@ -0,0 +1,57 @@
+# changes made from the default rendering of racket markdown
+
+code blocks have syntax highlighting baked by pygments. additionally, tex-style math expressions are
+baked to mathml using mathjax-node (this requires a polyfill on google chrome, which is filled in by
+nginx)
+
+# extensions provided on top of regular racket markdown
+
+## front matter
+
+front matter is an s-expr
+
+example
+
+```
+((date 2021 06 06)
+ (slug "meow")
+ (title "meow!")
+ (summary "the summary")
+ (tags "WaterDrinkers" "drinking" "water")
+ (authors "haskal"))
+
+regular markdown content here
+```
+
+front matter is required. if you have no front matter to provide, use an empty list:
+
+```
+()
+
+page content here
+```
+
+## hashtags
+
+a hashtag `#hashtag` appearing anywhere except in code and math blocks will be converted to a
+hashtag link which leads to an aggregate of all pages that use that tag (in the `tags` metadata)
+
+## xrefs
+
+pages go into a hierarchy based on their folders and the declared `slug` metadata (or slug derived
+from markdown filename - except for `index.md` which becomes the index in a certain folder).
+xrefs are a way to refer to slugs. xref can appear in links as follows
+
+```
+[some link](^some/page/xref)
+```
+
+## user links
+
+user pages can be linked to either with a freestanding mention or a link
+
+```
+@haskal
+
+[link to haskal](@haskal)
+```