~sircmpwn/sr.ht-docs

992575e3d5d11db7953961e8a83e26a4cd1e819f — ARaspiK 25 days ago 2cebd0b
Update markdown documentation

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

M markdown/index.md
M markdown/index.md => markdown/index.md +31 -31
@@ 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}`