From 992575e3d5d11db7953961e8a83e26a4cd1e819f Mon Sep 17 00:00:00 2001
From: ARaspiK <araspik@protonmail.com>
Date: Fri, 10 Jul 2020 14:31:43 +0000
Subject: Update markdown documentation

The recent misaka->mistletoe shift left the markdown documentation in
need of an update, so here it is.
---
 markdown/index.md | 62 +++++++++++++++++++++++++++----------------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

(limited to 'markdown/index.md')

diff --git a/markdown/index.md b/markdown/index.md
index 4837b34..c5816a8 100644
--- a/markdown/index.md
+++ b/markdown/index.md
@@ -2,65 +2,65 @@
 title: Markdown on sourcehut
 ---
 
-Across the site, sr.ht uses a consistent Markdown syntax based on Python's
-[Markdown](https://pypi.python.org/pypi/Markdown) package, which implements John
-Gruber's [original Markdown
-specification](https://daringfireball.net/projects/markdown/).
+Across the site, sr.ht uses [mistletoe][] for rendering Markdown.  It
+implements [CommonMark][], which is much more well-defined than the
+original Markdown specification.
 
-We then post-process the HTML to strip out unwanted tags and attributes.
+Additionally, some extensions to CommonMark are used.
 
-## Tags
+* Plain link URLs (of the form `<scheme>://<path>`) and plain e-mail
+  addresses (of the form `<name>@<domain>`) can be used, and they will
+  be turned into the appropriate links (for e-mail addresses, this
+  prepends `mailto:`).
 
-- `a`
-- `abbr`
-- `acronym`
+[mistletoe]: https://github.com/miyuchina/mistletoe
+[Commonmark]: https://spec.commonmark.org
+
+## Post-processing
+
+Rendered HTML is post-processed so that it only consists the following
+tags and attributes (in the format `tags...: attributes...`)
+
+- `a`: `href`, `title`
+- `abbr`: `title`
+- `acronym`: `title`
 - `b`
 - `blockquote`
 - `code`
-- `div`
 - `dd`
+- `div`
 - `dl`
 - `dt`
 - `em`
-- `h1`, `h2`, `h3`, `h4`, `h5`
+- `h1`, `h2`, `h3`, `h4`, `h5`, `h6`: `id`
 - `i`
-- `img`
-- `input`
+- `img`: `alt`, `height`, `width`, `src` (only HTTP/HTTPS/local URLs)
+- `input`: `type=checkbox`, `checked`, `disabled`
 - `li`
 - `ol`
 - `p`
 - `pre`
+- `q`
 - `span`
 - `strong`
 - `table`
 - `tbody`
-- `thead`
 - `td`
 - `th`
+- `thead`
 - `tr`
 - `ul`
 
-## Attributes
-
-We allow the `id` attribute on `h*` tags and the `class` attribute on all tags -
-the only permitted values of `class` are:
-
-- `row`
-- `col-md-*`
-- `form-control`
+All tags can have the attributes `class`, `style`, `colspan` and
+`rowspan`. The only allowed classes are `row`, `col-md-*`, and
+`form-control`.
 
-You may also specify the `style` tag, for which you may specify the following
-attributes:
+Here are valid `style` attributes:
 
 - `margin`
 - `padding`
 - `text-align`
 - `font-weight`
 - `text-decoration`
-
-`input` elements may specify `type='checkbox'` as well as the `checked`
-attribute.
-
-`a` tags may specify `href` and `title`.
-
-`abbr` and `acronym` tags may specify `title`.
+- `padding-{left,right,bottom,top}`
+- `margin-{left,right,bottom,top}`
-- 
cgit