summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Mehren2021-04-03 14:12:17 +0200
committerGitHub2021-04-03 14:12:17 +0200
commitc093c67c6718dc280ff535df59f5785ed5c23e7d (patch)
tree5ddddf3f390171fca3ccf13ddc5b0beba1fc017c
parent4f73d3ab98a4de739a4969685dbd876d31d4276a (diff)
parentf355cfc8643528809eb87bc9a66fda3a3433edc7 (diff)
Merge pull request #1091 from hedgedoc/improvement/add-hfm-docs
[Docs] Add "HedgeDoc flavored markdown" page
Diffstat (limited to '')
-rw-r--r--docs/content/references/hfm.md116
-rw-r--r--docs/mkdocs.yml2
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