3 ms·

Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either: 1. Embed HTML (more or less prefer

by dend 10y ago

Depends. We use Markdown pretty extensively and the drawbacks listed on the site don't really apply - you can always either: 1. Embed HTML (more or less preferred, depending on your situation). 2. Create an extension.

Arnavion 10y ago
>Embed HTML (more or less preferred, depending on your situation) But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use <pre><code> tags, but then you lose syntax highlighting. Actually I've always wondered why no MD renderer supports something like <code data-lang="js"> which it then treats the same as a ```js code block. Or a pseudo <x-markdown> element...
- skystrife 10y ago
  Kramdown supports this with markdown="1" as an attribute on html tags: http://kramdown.gettalong.org/syntax.html#html-blocks http://kramdown.gettalong.org/syntax.html#html-blocks
  - Arnavion 10y ago
    Not only are you correct, you allowed me to find an equivalent feature in CommonMark! If there is an empty line between some content and its wrapping HTML tags then that content will be interpreted as markdown. So <td> ```js console.log("Hello, world!"); ``` </td> will work as expected. http://spec.commonmark.org/0.26/#example-118 http://spec.commonmark.org/0.26/#example-118 and further discussion at http://spec.commonmark.org/0.26/#example-153 http://spec.commonmark.org/0.26/#example-153 VSCode's markdown preview renderer ( https://github.com/markdown-it/markdown-it https://github.com/markdown-it/markdown-it ) implements CommonMark, so I'm very happy right now :)
- LukeShu 10y ago
  > But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use <pre><code> tags, but then you lose syntax highlighting. Pandoc supports this with the `markdown_in_html_blocks` option.
grive 10y ago
3. Pick a language that already supports it and is stable, standardized, without having to whip out some specialized version just for your codebase.
- dend 10y ago
  Not like you have to do anything to get it to work OOB, but your mileage may vary. One of the benefits of Markdown is that it's easily understood by people new to the doc space. RST is slightly more complex and has more rules added in.

by dend 10y ago

Arnavion 10y ago

>Embed HTML (more or less preferred, depending on your situation) But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use <pre><code> tags, but then you lose syntax highlighting. Actually I've always wondered why no MD renderer supports something like <code data-lang="js"> which it then treats the same as a ```js code block. Or a pseudo <x-markdown> element...

skystrife 10y ago
Kramdown supports this with markdown="1" as an attribute on html tags: http://kramdown.gettalong.org/syntax.html#html-blocks http://kramdown.gettalong.org/syntax.html#html-blocks
- Arnavion 10y ago
  Not only are you correct, you allowed me to find an equivalent feature in CommonMark! If there is an empty line between some content and its wrapping HTML tags then that content will be interpreted as markdown. So <td> ```js console.log("Hello, world!"); ``` </td> will work as expected. http://spec.commonmark.org/0.26/#example-118 http://spec.commonmark.org/0.26/#example-118 and further discussion at http://spec.commonmark.org/0.26/#example-153 http://spec.commonmark.org/0.26/#example-153 VSCode's markdown preview renderer ( https://github.com/markdown-it/markdown-it https://github.com/markdown-it/markdown-it ) implements CommonMark, so I'm very happy right now :)
LukeShu 10y ago
> But then you can't embed markdown inside the HTML, like code blocks inside a table. Sure you can use <pre><code> tags, but then you lose syntax highlighting. Pandoc supports this with the `markdown_in_html_blocks` option.

grive 10y ago

3. Pick a language that already supports it and is stable, standardized, without having to whip out some specialized version just for your codebase.

dend 10y ago
Not like you have to do anything to get it to work OOB, but your mileage may vary. One of the benefits of Markdown is that it's easily understood by people new to the doc space. RST is slightly more complex and has more rules added in.