Merge pull request #1091 from hedgedoc/improvement/add-hfm-docs

[Docs] Add "HedgeDoc flavored markdown" page

2 files changed, 118 insertions, 0 deletions

diff --git a/docs/content/references/hfm.md b/docs/content/references/hfm.md
new file mode 100644
index 00000000..271d7cd3
--- /dev/null
+++ b/docs/content/references/hfm.md
@@ -0,0 +1,116 @@
+# HedgeDoc Flavored Markdown
+
+HedgeDoc mostly follows the [CommonMark][commonmark] standard. It shares some extensions with the [GFM][gfm] standard, but for historical reasons HedgeDoc does support not exactly GFM, but a bit more in places (and a bit less in other places).
+
+These tables will tell you what exactly we support in HedgeDoc 1.x (HFM 1) and will support in HedgeDoc 2 (HFM 2).
+
+**Please keep in mind that HedgeDoc 2 is still in development and not functional yet.**
+
+
+## Typography
+
+
+| Feature       | HFM 1 | HFM 2 | CommonMark          | GFM               |
+|---------------|:-----:|:-----:|:-------------------:|:-----------------:|
+| bold          | ☑️     | ☑️     | ☑️                   | ☑️                 |
+| italic        | ☑️     | ☑️     | ☑️                   | ☑️                 |
+| underline     | ☑️     | ☑️     | (☑️ with `<ins>`)    | (☑️ with `<ins>`)  |
+| strikethrough | ☑️     | ☑️     | (☑️ with `<del>`)    | ☑️                 |
+| subscript     | ☑️     | ☑️     | (☑️ with `<sub>`)    | (☑️ with `<sub>`)  |
+| superscript   | ☑️     | ☑️     | (☑️ with `<sup>`)    | (☑️ with `<sup>`)  |
+| marked        | ☑️     | ☑️     | (☑️ with `<mark>`)   | (☑️ with `<mark>`) |
+
+## Extended typography features
+
+| Feature                        | HFM 1 | HFM 2 | CommonMark | GFM |
+|--------------------------------|:-----:|:-----:|:----------:|:---:|
+| heading                        | ☑️     | ☑️     | ☑️          | ☑️   |
+| inline code                    | ☑️     | ☑️     | ☑️          | ☑️   |
+| indented code blocks           | ☑️     | ☑️     | ☑️          | ☑️   |
+| code block with language[^highlight]       | ☑️     | ☑️     | ☑️          | ☑️   |
+| code block with extra features[^extra-code] | ☑️     | ☑️     |            |     |
+| block quote                    | ☑️     | ☑️     | ☑️          | ☑️   |
+| name tag (`[name=...]`)        | (☑️)[^in-bq-list]     | ☑️     |            |     |
+| time tag (`[time=...]`)        | (☑️)[^in-bq-list]     | ☑️     |            |     |
+| color tag (`[color=...]`)      | (☑️)[^in-bq-list]     | ☑️     |            |     |
+| unorderd list                  | ☑️     | ☑️     | ☑️          | ☑️   |
+| ordered list                   | ☑️     | ☑️     | ☑️          | ☑️   |
+| task list                      | ☑️     | ☑️     |            | ☑️   |
+| defition list                  | ☑️     | ☑️     |            |     |
+| emoji             | [Unicode 6.1][unicode-6] | [Unicode 13][unicode-13] |                      |                      |
+| [ForkAwesome][fa] | ☑️ with `<i class='fa'>`  | ☑️ with shortcodes        |                      |                      |
+| LaTeX             | ☑️[^mj]                   | ☑️[^kt]                   |                      |                      |
+
+[^highlight]: Code-blocks with a given language are rendered with syntax-highlighting for the code.
+[^extra-code]: Several special "language" keywords can be used for rendering diagrams, charts, etc.
+[^in-bq-list]: Use of these tags is only supported within blockquotes or (un)ordered lists.
+[^mj]: LaTeX is rendered with [MathJax][mathjax].
+[^kt]: LaTeX is rendered with [KaTeX][katex].
+
+## Links & Images
+
+| Feature               | HFM 1 | HFM 2 | CommonMark       | GFM              |
+|-----------------------|:-----:|:-----:|:----------------:|:----------------:|
+| link                  | ☑️     | ☑️     | ☑️                | ☑️                |
+| link reference        | ☑️     | ☑️     | ☑️                | ☑️                |
+| link title            | ☑️     | ☑️     | ☑️                | ☑️                |
+| autolink with `<>`    | ☑️     | ☑️     | ☑️                | ☑️                |
+| autolink without `<>` | ☑️     | ☑️     |                  | ☑️                |
+| footnotes             | ☑️     | ☑️     |                  |                  |
+| image                 | ☑️     | ☑️     | ☑️                | ☑️                |
+| image with given size | ☑️     | ☑️     | (☑️ with `<img>`) | (☑️ with `<img>`) |
+| table of contents     | ☑️     | ☑️     |                  |                  |
+
+
+## Structural elements
+
+| Feature           | HFM 1                    | HFM 2                    | CommonMark           | GFM                  |
+|-------------------|:------------------------:|:------------------------:|:--------------------:|:--------------------:|
+| table             | ☑️                        | ☑️                        | (☑️ with `<table>`)   | ☑️                    |
+| horizontal line   | ☑️                        | ☑️                        | ☑️                    | ☑️                    |
+| collapsable block | (☑️ with `<details>`)     | ☑️                        | (☑️ with `<details>`) | (☑️ with `<details>`) |
+| Alerts            | ☑️                        | ☑️                        |                      |                      |
+
+## Embeddings
+HFM1 included support for certain embeddings of external content. These were defined in markdown by the uncommon `{%keyword parameter %}` syntax.
+
+Instead of this uncommon syntax, HFM2 uses just plain links to external content and creates embeddings for supported providers.
+
+| Feature                  | HFM 1 | HFM 2              | CommonMark | GFM |
+|--------------------------|:-----:|:------------------:|:----------:|:---:|
+| PDF (`{%pdf ... %}`)     | ☑️     | removed            |            |     |
+| [YouTube][youtube] (`{%youtube ... %}`)       | ☑️     | with plain link[^embed] |            |     |
+| [Vimeo][vimeo] (`{%vimeo ... %}`)          | ☑️     | with plain link[^embed] |            |     |
+| [Slideshare][slideshare] (`{%slideshare ... %}`) | ☑️     | removed            |            |     |
+| [Speakerdeck][speakerdeck] (`{%speakerdeck ... %}`) | ☑️     | removed            |            |     |
+| [GitHub Gist][gist] (`{%gist ... %}`)             | ☑️     | with plain link[^embed] |            |     |
+
+[^embed]: The special syntax is deprecated but will continue to work. However a plain link to the content will generate the same embedding and is preferred.
+
+## HTML
+Besides the basic HTML typography elements (`<p>`, `<a>`, `<b>`, `<ins>`, `<del>`) the following more special HTML elements are supported by some specification.
+
+|    Feature    | HedgeDocMark 1 | HedgeDocMark 2 | CommonMark | GFM |
+|:-------------:|:--------------:|:--------------:|:----------:|:---:|
+|   `<title>`   |                |                | ☑️          |     |
+|  `<textarea>` |                | ☑️              | ☑️          |     |
+|   `<style>`   | ☑️              | ☑️              | ☑️          |     |
+|    `<xmp>`    |                |                | ☑️          |     |
+|   `<iframe>`  | ☑️              | ☑️              | ☑️          |     |
+|  `<noembed>`  | ☑️              |                | ☑️          |     |
+|  `<noframes>` | ☑️              |                | ☑️          |     |
+|   `<script>`  |                |                | ☑️          |     |
+| `<plaintext>` |                | ☑️              | ☑️          |     |
+
+[fa]: https://forkaweso.me/
+[youtube]: https://www.youtube.com/
+[vimeo]: https://vimeo.com/
+[slideshare]: https://www.slideshare.net/
+[speakerdeck]: https://speakerdeck.com/
+[gist]: https://gist.github.com/
+[mathjax]: https://www.mathjax.org/
+[katex]: https://katex.org/
+[gfm]: https://github.github.com/gfm/
+[commonmark]: https://spec.commonmark.org/
+[unicode-6]: https://unicode.org/versions/Unicode6.1.0/
+[unicode-13]: https://unicode.org/versions/Unicode13.0.0/
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 41e80659..4a490c06 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -40,6 +40,8 @@ nav:
       - Migration Troubleshooting: guides/migration-troubleshooting.md
       - Terms of Use Setup: guides/providing-terms.md
   - Configuration: configuration.md
+  - References:
+    - 'HedgeDoc Flavored Markdown': references/hfm.md
   - Developer:
       - 'Getting Started': dev/getting-started.md
       - API: dev/api.md