termynal / termynal.py

Python markdown terminal. Built for mkdocs

Termynal

A lightweight and modern animated terminal window. Built for mkdocs.

Installation

Examples

Usage

Use <!-- termynal --> before code block

<!-- termynal -->

```
$ python script.py
```

Mkdocs integration

Declare the plugin:

...
plugins:
  - termynal
...

Optionally, pass options to the processor:

[...]
plugins:
  - termynal:
      prompt_literal_start:
        - "$"
        - ">"
[...]

This config allows you to use another prompt:

<!-- termynal -->

```
> pip install termynal
---> 100%
Installed
```

Credits

Thanks ines

Contribution

Contribution guidelines for this project

termynal.py's Issues

Progress bar is not responsive (or not respecting the limits)

To reproduce:

1. Open https://daxartio.github.io/termynal/ on a smartphone's browser (FF on Android for example or Firefox on Desktop and Ctrl + M)
2. The progress bar extends beyond the frame on the right:

How to make it compatible with pymodwnx.snippets?

Hi @daxartio,

Been a while. It's impressive to see the good job you made here since I had a look 👏.

I'm facing a case remembering me the race condition between processors we've met before but I've not investigated a lot.

Use case:

• a project with a well-documented README.md with termynal comment:

  [...]
  ## Installation
  
  <!-- termynal: {"prompt_literal_start": [">"], title: Terminal} -->
  
  ```sh
  > pip install mkdocs-rss-plugin
  ---> 100%
  RSS plugin for Mkdocs installed! Add 'rss' to your 'plugins' section in mkdocs.yml
  [...]
  ```
  

• a docs/index.md where I would like to reuse the README.md content using pymodwnx.snippets:

  --8<-- "README.md"
  [...]

Sadly the render is not working:

Any idea?

Animation doesn't start - fast and restart buttons do not render

Hey again

Sorry for opening a second issue. I don't think this one is due to a conflict with another plugin or extension.

The animation does not start. The termynal asset displays at its last frame without the "fast" or "restart" buttons appearing.

However, this only happens if i navigate to the page with termynal on it through the nav: menu. If I go to the page via the URL, the animation starts and everything appears as intended. Also, if I navigate to the page through the nav: menu and get the static image, if I do a refresh on the page, animation plays fine.

Full disclosure, I do not have this issue with the official docker image from squidfunk.

This is only occurring on the mkdocs-material package installed via PIP install.

I was just hoping that during the development of this plugin that you ran into this issue or something similar and might know a workaround.

Edit:

Once again this isn't an issue with your plugin. I know the "What", just not sure about the "Why" yet.

Contingent on how the nav menu is configured, links may not trigger a GET request. The lack of the GET request fails to trigger the termynal animation.

no such file

Hi!
I have an error:

<urlopen error [Errno 2] No such file or directory: '/tmp/mkdocs_9kqaovqd/termynal.css'>

Termynal and superfences compatibility

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?

Formatting issue with `rich` panels

Hi,

Thank you for this plugin, it has been good to see it's rapid evolution over the past couple of weeks 😄

Following the 0.7.0 update there appears to be a formatting issue when using terminal output contained within a rich panel:

Expected:

$ my-cli
 Usage: my-cli [OPTIONS] COMMAND [ARGS]...                                     
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --about               -a        Show the application about dialog and exit.  │
│ --version             -v        Show the application version and exit.       │
│ --install-completion            Install completion for the current shell.    │
│ --show-completion               Show completion for the current shell, to    │
│                                 copy it or customize the installation.       │
│ --help                          Show this message and exit.                  │
╰──────────────────────────────────────────────────────────────────────────────╯

Actual:

$ my-cli
 Usage: my-cli [OPTIONS] COMMAND [ARGS]...                                     
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮

│ --about               -a        Show the application about dialog and exit. │

│ --version             -v        Show the application version and exit. │

│ --install-completion            Install completion for the current shell. │

│ --show-completion               Show completion for the current shell, to │

│                                 copy it or customize the installation. │

│ --help                          Show this message and exit. │

╰──────────────────────────────────────────────────────────────────────────────╯

The line spacing is probably a css tweak I imagine, the collapsed white-space on the right I'm not too sure about.

Please let me know if you require an further info.

Need to custom size

Hello ! Please help me ! How to config resize bash . Thank you !

[Question] Support for multiline commands?

Hi! Awesome project!

I was wondering, is there a way to support multiline commands? E.g.:

$ some longish command with \
    many \
    many \
    arguments
and this is the output

Currently, the "typing" animation only works for the first line of the command and the three additional command lines are interpreted as output and shown instantly after the animation finishes:

    many \
    many \
    arguments
and this is the output

Thanks!

Support for code blocks with language specified

Hi!

I noticed that, when specifying the language of a code block as in the following

```bash
$ git lfs install
Updated git hooks.
Git LFS initialized.
```

the actual command ($ git lfs install here) will not be identified as such, but it looks like it's treated as an output. However, some markdown linters discourage not specifying a language (e.g. MD040).

Maybe support for specifying a language could be added, and thinking further, maybe it could even be used to change the name of the shell in the header of rendered termynal frames (which defaults to "bash" right now). So when people prefer showing commands for zsh, they could specify this by doing

```zsh
$ command goes here
...
```

multi-line command issue and minify plugin

Hello,

I'm running into an issue with mutli-line commands.

when i do

> does this work \
  second command
output

i get the first two lines in one line

Add "restart" and "faster" button to animation in termynal

Inspired on FastAPI documentation I noticed that there are two buttons very useful and elegant. One button to restarts the animation and another button to makes the animation go faster.

See the examples:

Fast button

Restart button

And this is the termynal from the Termynal plugin:

Does it make sense to implement these buttons in the project?

Support for multiline output

I expect after entering a command that output will be without the animation.

For example

<!-- termynal -->

```
$ poetry --help

Description:
  Lists commands.

Usage:
  list [options] [--] [<namespace>]
```

The example here

Support within lists, admonitions, and content tabs

Hello, love the project! Thanks for your hard work.

I think it would be great if the terminals could be embedded below lists, and within admonitions / content tabs.

Thanks!

Regular expression error in FENCED_BLOCK_RE

The current regular expression doesn't match Termynal code blocks correctly.

For example:

 Welcome

One:

```yaml title="files/one.yml"
--8<-- "files/one.yml"
```

Two:

```yaml title="files/two.yml"
--8<-- "files/two.yml"
```

<!-- termynal -->

```
$ command

Ok!
```

Two blocks are selected when only one should be:

```

Two:

```yaml title="files/two.yml"
--8<-- "files/two.yml"
```

```
$ command

Ok!
```

This leads to errors, for example, when using the pymdownx.snippets extension (--8<-- notation).
example.zip

Plugin crashes when a raw HTML div with `markdown` attribute is present into Markdown pages

Thanks for your markdown processor and Mkdocs plugin.

Trying to use it in my Mdkocs website, the plugin crashes with pages containing not pure Markdown. Typically, I'm using grids from Material for Mkdocs and I was facing this error message during build:

ERROR    -  Error reading page 'team/sponsoring.md': 'xml.etree.ElementTree.Element' object has no attribute 'startswith'
Traceback (most recent call last):
  File "/home/username/Git/Geotribu/website/.venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/mkdocs/__main__.py", line 234, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 83, in serve
    builder(config)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 76, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/mkdocs/commands/build.py", line 308, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/mkdocs/commands/build.py", line 181, in _populate_page
    page.render(config, files)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/mkdocs/structure/pages.py", line 270, in render
    self.content = md.convert(self.markdown)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/markdown/core.py", line 261, in convert
    self.lines = prep.run(self.lines)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/termynal/markdown.py", line 46, in run
    lines_by_placeholder = self._get_lines(lines, content_by_placeholder)
  File "/home/username/Git/Geotribu/website/.venv/lib/python3.10/site-packages/termynal/markdown.py", line 64, in _get_lines
    if content.startswith(self.comment):
AttributeError: 'xml.etree.ElementTree.Element' object has no attribute 'startswith'

Note that it's a kind of conflict with Markdown in HTML extension.

I've used the reproduction method from Material for Mkdocs to provide a reproductible example:

example.zip

PR is coming.

Support for custom CSS

Termynal can be customized quite heavily with CSS alone.

For example, I replace the MacOS-like modal buttons with standard '- ⛶ X' text.

And I replace the title "bash", with plain "shell".

And if the language is "powershell", I set the prefix to 'PS >'.

Similarly, for "python", the prefix is '>>>'.

Rather than baking all this into this tool, if this tool could allow me to point to a custom CSS file, it would simplify the Termynal-related markdown I maintain today.