MkDocs plugin that adds a configurable shell-ps1 code fence with copy-safe prompt character
Project description
superfences-ps1
MkDocs plugin that adds a configurable shell-prompt SuperFences fence with copy-safe PS1 prompt characters.
The plugin registers a custom SuperFences
fence (default name shell-ps1) that prepends a configurable PS1 prompt character to every command line. The prompt is
rendered visibly in the documentation but is never copied to the clipboard and is never selected by mouse —
the plugin injects a data-copy attribute with the raw source text so Material for MkDocs' copy button bypasses the
prompt spans entirely, and user-select: none CSS is injected to prevent mouse selection of the prompt.
Installation
pip install superfences-ps1
Or with uv:
uv add superfences-ps1
Requirements
pymdownx.superfencesmust be listed undermarkdown_extensionsinmkdocs.yaml
Usage
mkdocs.yaml configuration
plugins:
- superfences-ps1:
fence_name: shell-ps1 # fence language identifier (default: shell-ps1)
prompt_char: "$" # PS1 prompt character prepended to each line (default: $)
prompt_color: "#5fb3b3" # optional CSS color for the prompt character
markdown_extensions:
- pymdownx.superfences
Writing shell fences
Use the configured fence_name in your markdown:
```shell-ps1
echo "Hello, world!"
ls -la
```
The plugin prepends the prompt character to each non-empty line before passing the content to Pygments. The rendered output shows the prompt visually, but the copy button and mouse selection only grab the commands themselves.
Configuration options
| Option | Type | Default | Description |
|---|---|---|---|
fence_name |
str |
shell-ps1 |
The fence language identifier used in markdown |
prompt_char |
str |
$ |
The PS1 prompt character prepended to each command line |
prompt_color |
str or None |
None |
Optional CSS color value for the rendered prompt |
[!NOTE]
prompt_charmust be one of$,%, or#— the only characters Pygments'BashSessionLexerrecognises as prompt markers, emitting them asGeneric.Prompt(.gp) tokens. Any other value will cause aPluginErrorat build time.>in particular is the continuation prompt (_ps2) and causes the entire line to be tokenised asGeneric.Output(.go), which would treat the command text as output.
How it works
- On
on_config, the plugin validates thatpymdownx.superfencesis present and injects a custom fence formatter intomdx_configs["pymdownx.superfences"]["custom_fences"]. - When MkDocs processes a page containing a fenced code block with the configured
fence_name, SuperFences calls the injected formatter. - The formatter prepends
<prompt_char>to every non-empty line, then passes the result to Pygments using theconsole(BashSessionLexer) lexer. Pygments wraps the prompt in<span class="gp">and the command in additional token spans. - The formatter injects a
data-copyattribute on the wrapper<div>containing the raw (un-prompted) source. Material for MkDocs' copy button readsdata-copyin preference toinnerText, so the prompt is never included in clipboard content. - On
on_post_page, the plugin injects a<style>block into each page's<head>withuser-select: noneon.gpspans, preventing mouse selection of the prompt. Ifprompt_coloris configured, the color rule is combined into the same<style>block.
Development
git clone https://github.com/dusktreader/superfences-ps1
cd superfences-ps1
uv sync
make qa/full
License
MIT — see LICENSE.md.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file superfences_ps1-0.1.0.tar.gz.
File metadata
- Download URL: superfences_ps1-0.1.0.tar.gz
- Upload date:
- Size: 5.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.1 {"installer":{"name":"uv","version":"0.11.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
17334254064954d03204fb80c0c2e1e9634390934c34c07f95caecdc79803e0f
|
|
| MD5 |
b784c1c33be3215992e6268b6dd456a9
|
|
| BLAKE2b-256 |
c44c7de690a91a0d57f1f41859051474ab03f0a8a17b0832051412081147e77d
|
File details
Details for the file superfences_ps1-0.1.0-py3-none-any.whl.
File metadata
- Download URL: superfences_ps1-0.1.0-py3-none-any.whl
- Upload date:
- Size: 7.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.11.1 {"installer":{"name":"uv","version":"0.11.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
eed17bf0a457cb0333f496becc42c7f0e497d504070ba3aa29cb9816e37bfdb9
|
|
| MD5 |
3d0b0fa2f1bcc2ce1a6738d302a93689
|
|
| BLAKE2b-256 |
92b7c84f4cf96a04c79d4a621be132ccdf7aff566dbbc4580c531d68bb018428
|
