From 60f73a5c8424f25a79fbdee48bde2ad168bbb418 Mon Sep 17 00:00:00 2001 From: Philip Molares Date: Thu, 25 Mar 2021 22:20:45 +0100 Subject: [PATCH 1/2] Docs: Add hedgedoc flavored markdown reference Signed-off-by: Philip Molares --- docs/content/references/hfm.md | 114 +++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 2 + 2 files changed, 116 insertions(+) create mode 100644 docs/content/references/hfm.md diff --git a/docs/content/references/hfm.md b/docs/content/references/hfm.md new file mode 100644 index 000000000..60e678d16 --- /dev/null +++ b/docs/content/references/hfm.md @@ -0,0 +1,114 @@ +# 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 HedgeDoc 2 (HFM 2). + + +## Typography + + +| Feature | HFM 1 | HFM 2 | CommonMark | GFM | +|---------------|:-----:|:-----:|:-------------------:|:-----------------:| +| bold | ☑️ | ☑️ | ☑️ | ☑️ | +| italic | ☑️ | ☑️ | ☑️ | ☑️ | +| underline | ☑️ | ☑️ | (☑️ with ``) | (☑️ with ``) | +| strikethrough | ☑️ | ☑️ | (☑️ with ``) | ☑️ | +| subscript | ☑️ | ☑️ | (☑️ with ``) | (☑️ with ``) | +| superscript | ☑️ | ☑️ | (☑️ with ``) | (☑️ with ``) | +| marked | ☑️ | ☑️ | (☑️ with ``) | (☑️ with ``) | + +## 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 `` | ☑️ 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 ``) | (☑️ with ``) | +| table of contents | ☑️ | ☑️ | | | + + +## Structural elements + +| Feature | HFM 1 | HFM 2 | CommonMark | GFM | +|-------------------|:------------------------:|:------------------------:|:--------------------:|:--------------------:| +| table | ☑️ | ☑️ | (☑️ with ``) | ☑️ | +| horizontal line | ☑️ | ☑️ | ☑️ | ☑️ | +| collapsable block | (☑️ with `
`) | ☑️ | (☑️ with `
`) | (☑️ with `
`) | +| 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 (`

`, ``, ``, ``, ``) the following more special HTML elements are supported by some specification. + +| Feature | HedgeDocMark 1 | HedgeDocMark 2 | CommonMark | GFM | +|:-------------:|:--------------:|:--------------:|:----------:|:---:| +| `` | | | ☑️ | | +| `<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 1851ae25b..b0dbb16b1 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -9,6 +9,8 @@ nav: - Home: index.md - Interface: Toolbar: interface/toolbar.md + - References: + 'HedgeDoc Flavored Markdown': references/hfm.md - Developer: - '2.0 Development': dev/2.0.md - Configuration: dev/config.md From c4e5ffbe7a6dd189d4b889063041063d2fd85e33 Mon Sep 17 00:00:00 2001 From: Philip Molares <philip.molares@udo.edu> Date: Sun, 28 Mar 2021 20:24:45 +0200 Subject: [PATCH 2/2] Docs: Add footnotes extension Signed-off-by: Philip Molares <philip.molares@udo.edu> --- docs/content/references/hfm.md | 14 ++++++-------- docs/mkdocs.yml | 1 + 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/content/references/hfm.md b/docs/content/references/hfm.md index 60e678d16..c72746606 100644 --- a/docs/content/references/hfm.md +++ b/docs/content/references/hfm.md @@ -1,8 +1,8 @@ # 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). +HedgeDoc has its own markdown dialect which supports many features from [CommonMark][commonmark] and [Github Flavored Markdown][gfm]. It also adds some new extensions and is missing some. -These tables will tell you what exactly we support in HedgeDoc 1.x (HFM 1) and HedgeDoc 2 (HFM 2). +These tables tell you what exactly we support in HedgeDoc 1.x (HFM 1) and HedgeDoc 2 (HFM 2). ## Typography @@ -39,9 +39,9 @@ These tables will tell you what exactly we support in HedgeDoc 1.x (HFM 1) and H | [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. +[^highlight]: Code blocks with a given language are rendered using syntax highlighting. [^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. +[^in-bq-list]: Use of these tags is only supported within blockquotes and (un)ordered lists. [^mj]: LaTeX is rendered with [MathJax][mathjax]. [^kt]: LaTeX is rendered with [KaTeX][katex]. @@ -70,9 +70,7 @@ These tables will tell you what exactly we support in HedgeDoc 1.x (HFM 1) and H | 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. +HFM 1 includes support for certain embeddings of external content by using the `{%keyword parameter %}` syntax. To increase the readability of the markdown code we decided that HFM 2 should just use plain links if possible. | Feature | HFM 1 | HFM 2 | CommonMark | GFM | |--------------------------|:-----:|:------------------:|:----------:|:---:| @@ -83,7 +81,7 @@ Instead of this uncommon syntax, HFM2 uses just plain links to external content | [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. +[^embed]: The special syntax from HFM 1 is deprecated, but will still work in HFM 2. However, a plain link to the content should be used. ## HTML Besides the basic HTML typography elements (`<p>`, `<a>`, `<b>`, `<ins>`, `<del>`) the following more special HTML elements are supported by some specification. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b0dbb16b1..a082f3505 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -21,6 +21,7 @@ markdown_extensions: permalink: true - admonition - attr_list + - footnotes theme: name: 'material' language: en