pdoc icon indicating copy to clipboard operation
pdoc copied to clipboard

Code blocks broken inside markdown `!!! note` admonitions

Open davfsa opened this issue 5 years ago • 1 comments

Expected Behavior

Markdown is parsed properly

Actual Behavior

Weird behavior happens or wrong language gets parsed

Steps to Reproduce

  1. Have a !!! note with a codeblock in it.
    unknown

  2. Build the html and look at the output. unknown2

Additional notes

Intending the codeblock causes it to be detected as shell unknown3

Also detects it as shell if you only intent it, even without the codeblock unknown4

You can see a repo here: repro_API_documentation.txt NOTE: Github doesnt allow uploading html, so you will have to download that and rename the extension to .html to view it

Additional info

  • pdoc version: 0.8.1

davfsa avatar Jun 06 '20 11:06 davfsa

Thanks for the report. This is actually an upstream issue:

  • Highlight.js for improper highlighting of short code snippets, and
  • Python-Markdown for non-interpretation of nested fenced code blocks (see/subscribe/voice/fix https://github.com/Python-Markdown/markdown/issues/53).
$ markdown_py -x fenced_code -x admonition << 'EOF'

!!! note
    Let's see:

    >>> Markdown has no notion of doctests,
    >>> so this will become a blockquote

    Blah blah

    ```py
    # This should be python code, but Python-Markdown
    # says fenced code blocks only supported at document root level
    # https://python-markdown.github.io/extensions/fenced_code_blocks/
    ```

    Blah blah blah

        ```py
        # This will become _indented_ code block, hence 
        # ignoring the fence and its language annotation
        ```

    Big sad :(

EOF
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Let's see:</p>
<blockquote>
<blockquote>
<blockquote>
<p>Markdown has no notion of doctests,
so this will become a blockquote</p>
</blockquote>
</blockquote>
</blockquote>
<p>Blah blah</p>
<p>```py</p>
<h1>This should be python code, but Python-Markdown</h1>
<h1>says fenced code blocks only supported at document root level</h1>
<h1>https://python-markdown.github.io/extensions/fenced_code_blocks/</h1>
<p>```</p>
<p>Blah blah blah</p>
<pre><code>```py
# This will become _indented_ code block, hence 
# ignoring the fence and its language annotation
```
</code></pre>
<p>Big sad :(</p>

kernc avatar Jun 11 '20 12:06 kernc