Merge pull request #1091 from hedgedoc/improvement/add-hfm-docs
[Docs] Add "HedgeDoc flavored markdown" page
This commit is contained in:
David Mehren
GitHub
commit
c093c67c67
116
docs/content/references/hfm.md
Normal file
116
docs/content/references/hfm.md
Normal file
@ -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/
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user