Termynal and superfences compatibility

[JChoi54]

I can't get the termynal animation to work while using superfences. This is likely because superfences uses similar syntax:

  example fenced block

Is there a way around this?

[daxartio]

Can you give an example about this?

[Guts]

I've reproduced the same bug with a typical configuration of Material for Mkdocs when you need to display Mermaid diagrams (superfences) AND using a custom configuration for highlight (both from the unmissable pymdown-extensions from @facelessuser:

Working

With superfences, withou highlight

site_name: "Termynal"
site_url: "https://pypi.org/project/termynal"
site_description: ""

repo_name: "termynal"
repo_url: "https://github.com/daxartio/termynal"
edit_uri: "edit/main/docs/"

copyright: "Copyright &copy; 2021 Danil Akhtarov <daxartio@gmail.com>"

nav:
  - "Home": README.md

theme:
  name: material
  language: en
  palette:
    primary: black
    accent: yellow

plugins:
  - termynal
  - search:
      lang: en

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - termynal:
      prompt_literal_start:
        - "$ "
        - "&gt; "

Without superfences, with highlight

site_name: "Termynal"
site_url: "https://pypi.org/project/termynal"
site_description: ""

repo_name: "termynal"
repo_url: "https://github.com/daxartio/termynal"
edit_uri: "edit/main/docs/"

copyright: "Copyright &copy; 2021 Danil Akhtarov <daxartio@gmail.com>"

nav:
  - "Home": README.md

theme:
  name: material
  language: en
  palette:
    primary: black
    accent: yellow

plugins:
  - termynal
  - search:
      lang: en

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      linenums: true
      line_spans: __span
      pygments_lang_class: true
      use_pygments: true
  - termynal:
      prompt_literal_start:
        - "$ "
        - "&gt; "

Not working: with superfences and highlight

site_name: "Termynal"
site_url: "https://pypi.org/project/termynal"
site_description: ""

repo_name: "termynal"
repo_url: "https://github.com/daxartio/termynal"
edit_uri: "edit/main/docs/"

copyright: "Copyright &copy; 2021 Danil Akhtarov <daxartio@gmail.com>"

nav:
  - "Home": README.md

theme:
  name: material
  language: en
  palette:
    primary: black
    accent: yellow

plugins:
  - termynal
  - search:
      lang: en

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
      linenums: true
      line_spans: __span
      pygments_lang_class: true
      use_pygments: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - termynal:
      prompt_literal_start:
        - "$ "
        - "&gt; "

Recorded screen with unworking behavior

CSS is OK, typing animation is OK but not the progress bar.

termynal_incomplete_animation.webm

[Guts]

@JChoi54 do you confirm that it's the same bug?

[Guts]

Ok, disabling the options of highlight (anchor_linenums: true and line_spans: __span) concerning the line numbers, it's working:

site_name: "Termynal"
site_url: "https://pypi.org/project/termynal"
site_description: ""

repo_name: "termynal"
repo_url: "https://github.com/daxartio/termynal"
edit_uri: "edit/main/docs/"

copyright: "Copyright &copy; 2021 Danil Akhtarov <daxartio@gmail.com>"

nav:
  - "Home": README.md

theme:
  name: material
  language: en
  palette:
    primary: black
    accent: yellow

plugins:
  - termynal
  - search:
      lang: en

markdown_extensions:
  - pymdownx.highlight:
      pygments_lang_class: true
      use_pygments: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - termynal:
      prompt_literal_start:
        - "$ "
        - "&gt; "

[Guts]

To options are conflicting the Material theme requirements for some features:

• https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.line_spans
• https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.anchor_linenums

Ref: https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#configuration

[Guts]

@daxartio you should maybe report it to @squidfunk, at least to add a warning to documentations or, with luck, an idea to solve conflitcs?

[Guts]

Sorry to flood, here comes differences between HTML output using this markdown:

<!-- termynal -->

$ pip install termynal ---> 100% Installed

Normal

<!-- termynal -->

<p>
<div class="termy" data-termynal>
  <span data-ty="input" data-ty-prompt="$">pip install termynal</span>
  <span data-ty="progress"></span>
  <span data-ty>Installed</span>
  <span data-ty></span>
</div>
</p>

With anchor_linenums: true

<!-- termynal -->

<p>
<div class="termy" data-termynal>
  <span data-ty="input" data-ty-prompt="$">pip install termynal</span>
  <span data-ty><a id="__codelineno-0-2" name="__codelineno-0-2"></a>---&gt; 100%</span>
  <span data-ty><a id="__codelineno-0-3" name="__codelineno-0-3"></a>Installed</span>
  <span data-ty></span>
</div>
</p>

With line_spans: __span

<!-- termynal -->

<p>
<div class="termy" data-termynal>
  <span data-ty="input" data-ty-prompt="$">pip install termynal</span>
  <span data-ty></span><span id="__span-0-2">---&gt; 100%</span>
  <span data-ty></span><span id="__span-0-3">Installed</span>
  <span data-ty></span></span>
</div>
</p>

With both anchor_linenums: true and line_spans: __span

<!-- termynal -->

<p>
<div class="termy" data-termynal>
  <span data-ty="input" data-ty-prompt="$">pip install termynal</span>
  <span data-ty></span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2"></a>---&gt;
    100%</span>
  <span data-ty></span><span id="__span-0-3"><a id="__codelineno-0-3"
      name="__codelineno-0-3"></a>Installed</span>
  <span data-ty></span></span>
</div>
</p>

[facelessuser]

I am the author of SuperFences. Can someone explain to me how Termynal works? More specifically, I see it is composed of two parts. A Python Markdown part and a MkDocs part. What does the Python Markdown part do so it can expose what it needs to the MkDocs part I may be able to recommend something, but I need to understand what you are doing and why you are doing it.

[facelessuser]

Or is the only problem with the MkDocs styling due to format outputs? Since I was tagged, I'm trying to assess whether there are any direct questions you are hoping to have answered.

[Guts]

Hi @facelessuser, thanks for joining us on this.

As said above, termynal is a Python Markdown extension with a (minimal) integration within Mkdocs. It allows to set a code block as a termynal, from the name of this project https://github.com/ines/termynal showing commands in a fancy and animated terminal.

When using with some options (line_spans: __span and anchor_linenums) of your highlight extension, the animation (span) is broken. I've just posted the outputs.

Do you have an idea how to conciliate both processors?

[facelessuser]

Can you be a bit more specific, from a Termynal perspective? What do you find broken? I see that enabling the two options is problematic for Termynal, but from Termynal's perspective, why is this breaking animations? Can you summarize the issue?

[daxartio]

@Guts thank you for your explanations and the examples.

Actually it seems like a hard task to resolve.

[facelessuser]

Is highlighting required by your plugin? I'm still trying to understand the root issue. Do you just need the plain text to process?

[daxartio]

The plugin converts md to html in TermynalPreprocessor.

From:

# Header

```console
$ pip install termynal
---> 100%

To:

```html
<h1>Header</h1>
<p>
<div class="termy" data-termynal>
<span data-ty="input" data-ty-prompt="$">pip&nbsp;install&nbsp;termynal</span>
<span data-ty="progress"></span>
<span data-ty></span>
</div></p>

Is highlighting required by your plugin? I'm still trying to understand the root issue. Do you just need the plain text to process?

At the moment i don't know

[Guts]

Is highlighting required by your plugin?

No. The issue is about using both plugins in the same Markdown/Mkdocs configuration. They are conflicting on span tags.

[daxartio]

I see. But i don't know how i can fix that.

Why does your plugin convert a code block to html with custom classes if my plugin converts it before? Or your plugin starts before?

[daxartio]

I checked. If i change priority of my plugin in the md preprocessors from 20 to 2000 i see as a result changes of your plugin

[facelessuser]

It sounds like we have two plugins fighting for the same content. SuperFences takes great care to make sure it captures all fenced code blocks. Generally, it is recommended to create a custom fence. Custom fence can even override existing languages.

[facelessuser]

The reason for the creation of SuperFences was to ensure sane processing of fenced code blocks nested under lists, blockquote, and other constructs, something the default fenced_code extension in Python Markdown doesn't do well at. Custom fences allow for others to leverage that and process the content however they want. Now, maybe you don't want to create a custom fences for people to use with SuperFences, I don't know, but if you don't, I would have to understand how your plugin process content.

If you are processing the content before SuperFences via a preprocessor, SuperFences shouldn't see it, but Highlight will process HTML code blocks in the etree structure. The format you use doesn't look like it is using code blocks (based on what you posted here), but instead is using divs, but I haven't looked at your code to follow the entire process. If you are using code blocks, you can put them in the Python Markdown HTML stash and Highlight won't see them. I imagine that is what you are doing if you are using a preprocessor, but maybe not.

[Guts]

If I get your point @facelessuser the idea would be to write a custom fence that integrates with superfences and callable like this:

    markdown_extensions:
        - ...
        - ...
        - pymdownx.superfences:
            custom_fences:
                - name: termynal
                  class: termynal
                  format: !!python/name:termynal.fence_termynal

[facelessuser]

Yep, that is one approach. If you are partial to using console, the user can override that name.

[daxartio]

Fixed in v0.8.0

Thank you!

[Guts]

Thanks you @daxartio for the fix and the quick release, it's really cool!