The Problem with Linux Kernel Documentation, and How We're Fixing It

Re:The Problem with Linux Kernel Documentation, and How We'r... by Arnavion on Wednesday September 28, 2016 @02:26PM (#12600022)

>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...

[ Parent | on HN ]

Re:The Problem with Linux Kernel Documentation, and How We'r... by skystrife on Wednesday September 28, 2016 @03:39PM (#12600626)

Kramdown supports this with markdown="1" as an attribute on html tags: http://kramdown.gettalong.org/syntax.html#html-blocks

[ Parent | on HN ]

Re:The Problem with Linux Kernel Documentation, and How We'r... by Arnavion on Wednesday September 28, 2016 @04:12PM (#12600920)

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 and further discussion at http://spec.commonmark.org/0.26/#example-153

VSCode's markdown preview renderer ( https://github.com/markdown-it/markdown-it ) implements CommonMark, so I'm very happy right now :)

[ Parent | on HN ]

Re:The Problem with Linux Kernel Documentation, and How We'r... by LukeShu on Wednesday September 28, 2016 @04:17PM (#12600973)

> 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.

[ Parent | on HN ]