superfences-ps1 0.1.0__tar.gz

superfences_ps1-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) `2026` `Tucker Beck`
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

superfences_ps1-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: superfences-ps1
+Version: 0.1.0
+Summary: MkDocs plugin that adds a configurable shell-ps1 code fence with copy-safe prompt character
+Keywords: mkdocs,mkdocs-plugin,plugin,pymdownx,superfences,shell,ps1,pygments,documentation,documentation-tools,mkdocs-material
+Author: Tucker Beck
+Author-email: Tucker Beck <tucker.beck@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: MkDocs
+Classifier: Topic :: Documentation
+Requires-Dist: mkdocs>=1.5.0
+Requires-Dist: pymdown-extensions>=10.0
+Requires-Dist: pygments>=2.16
+Requires-Python: >=3.12
+Project-URL: homepage, https://github.com/dusktreader/superfences-ps1
+Project-URL: source, https://github.com/dusktreader/superfences-ps1
+Project-URL: changelog, https://github.com/dusktreader/superfences-ps1/blob/main/CHANGELOG.md
+Project-URL: issues, https://github.com/dusktreader/superfences-ps1/issues
+Description-Content-Type: text/markdown
+
+# superfences-ps1
+
+MkDocs plugin that adds a configurable shell-prompt SuperFences fence with copy-safe PS1 prompt characters.
+
+The plugin registers a custom [SuperFences](https://facelessuser.github.io/pymdown-extensions/extensions/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
+
+```shell
+pip install superfences-ps1
+```
+
+Or with uv:
+
+```shell
+uv add superfences-ps1
+```
+
+
+## Requirements
+
+- `pymdownx.superfences` must be listed under `markdown_extensions` in `mkdocs.yaml`
+
+
+## Usage
+
+
+### `mkdocs.yaml` configuration
+
+```yaml
+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:
+
+````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_char` must be one of `$`, `%`, or `#` — the only characters Pygments' `BashSessionLexer` recognises as
+> prompt markers, emitting them as `Generic.Prompt` (`.gp`) tokens. Any other value will cause a `PluginError` at
+> build time. `>` in particular is the continuation prompt (`_ps2`) and causes the entire line to be tokenised as
+> `Generic.Output` (`.go`), which would treat the command text as output.
+
+
+## How it works
+
+1. On `on_config`, the plugin validates that `pymdownx.superfences` is present and injects a custom fence formatter
+   into `mdx_configs["pymdownx.superfences"]["custom_fences"]`.
+2. When MkDocs processes a page containing a fenced code block with the configured `fence_name`, SuperFences calls
+   the injected formatter.
+3. The formatter prepends `<prompt_char> ` to every non-empty line, then passes the result to Pygments using the
+   `console` (`BashSessionLexer`) lexer. Pygments wraps the prompt in `<span class="gp">` and the command in
+   additional token spans.
+4. The formatter injects a `data-copy` attribute on the wrapper `<div>` containing the raw (un-prompted) source.
+   Material for MkDocs' copy button reads `data-copy` in preference to `innerText`, so the prompt is never included
+   in clipboard content.
+5. On `on_post_page`, the plugin injects a `<style>` block into each page's `<head>` with `user-select: none` on
+   `.gp` spans, preventing mouse selection of the prompt. If `prompt_color` is configured, the color rule is
+   combined into the same `<style>` block.
+
+
+## Development
+
+```shell
+git clone https://github.com/dusktreader/superfences-ps1
+cd superfences-ps1
+uv sync
+make qa/full
+```
+
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

superfences_ps1-0.1.0/README.md

@@ -0,0 +1,106 @@
+# superfences-ps1
+
+MkDocs plugin that adds a configurable shell-prompt SuperFences fence with copy-safe PS1 prompt characters.
+
+The plugin registers a custom [SuperFences](https://facelessuser.github.io/pymdown-extensions/extensions/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
+
+```shell
+pip install superfences-ps1
+```
+
+Or with uv:
+
+```shell
+uv add superfences-ps1
+```
+
+
+## Requirements
+
+- `pymdownx.superfences` must be listed under `markdown_extensions` in `mkdocs.yaml`
+
+
+## Usage
+
+
+### `mkdocs.yaml` configuration
+
+```yaml
+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:
+
+````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_char` must be one of `$`, `%`, or `#` — the only characters Pygments' `BashSessionLexer` recognises as
+> prompt markers, emitting them as `Generic.Prompt` (`.gp`) tokens. Any other value will cause a `PluginError` at
+> build time. `>` in particular is the continuation prompt (`_ps2`) and causes the entire line to be tokenised as
+> `Generic.Output` (`.go`), which would treat the command text as output.
+
+
+## How it works
+
+1. On `on_config`, the plugin validates that `pymdownx.superfences` is present and injects a custom fence formatter
+   into `mdx_configs["pymdownx.superfences"]["custom_fences"]`.
+2. When MkDocs processes a page containing a fenced code block with the configured `fence_name`, SuperFences calls
+   the injected formatter.
+3. The formatter prepends `<prompt_char> ` to every non-empty line, then passes the result to Pygments using the
+   `console` (`BashSessionLexer`) lexer. Pygments wraps the prompt in `<span class="gp">` and the command in
+   additional token spans.
+4. The formatter injects a `data-copy` attribute on the wrapper `<div>` containing the raw (un-prompted) source.
+   Material for MkDocs' copy button reads `data-copy` in preference to `innerText`, so the prompt is never included
+   in clipboard content.
+5. On `on_post_page`, the plugin injects a `<style>` block into each page's `<head>` with `user-select: none` on
+   `.gp` spans, preventing mouse selection of the prompt. If `prompt_color` is configured, the color rule is
+   combined into the same `<style>` block.
+
+
+## Development
+
+```shell
+git clone https://github.com/dusktreader/superfences-ps1
+cd superfences-ps1
+uv sync
+make qa/full
+```
+
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

superfences_ps1-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "superfences-ps1"
+version = "0.1.0"
+description = "MkDocs plugin that adds a configurable shell-ps1 code fence with copy-safe prompt character"
+authors = [
+  {name = "Tucker Beck", email = "tucker.beck@gmail.com"}
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+keywords = [
+  "mkdocs",
+  "mkdocs-plugin",
+  "plugin",
+  "pymdownx",
+  "superfences",
+  "shell",
+  "ps1",
+  "pygments",
+  "documentation",
+  "documentation-tools",
+  "mkdocs-material",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: MkDocs",
+  "Topic :: Documentation",
+]
+requires-python = ">=3.12"
+dependencies = [
+  "mkdocs>=1.5.0",
+  "pymdown-extensions>=10.0",
+  "pygments>=2.16",
+]
+
+[project.entry-points."mkdocs.plugins"]
+superfences-ps1 = "superfences_ps1.plugin:ShellPromptPlugin"
+
+[project.urls]
+homepage = "https://github.com/dusktreader/superfences-ps1"
+source = "https://github.com/dusktreader/superfences-ps1"
+changelog = "https://github.com/dusktreader/superfences-ps1/blob/main/CHANGELOG.md"
+issues = "https://github.com/dusktreader/superfences-ps1/issues"
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = [
+  "mkdocs-material~=9.6",
+  "pre-commit>=4.5.1",
+  "pyclean~=3.1",
+  "pygments~=2.19",
+  "pytest~=8.3",
+  "pytest-cov~=6.0",
+  "pytest-pretty~=1.2",
+  "pytest-random-order~=1.1",
+  "ruff~=0.11",
+  "ty>=0.0.0a1",
+  "types-markdown>=3.10.2.20260211",
+  "typos~=1.31",
+  "yamllint>=1.38.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+addopts = [
+  "--random-order",
+  "--cov=src/superfences_ps1",
+  "--cov-report=term-missing",
+  "--cov-fail-under=85",
+]
+
+[tool.ruff]
+line-length = 120
+src = ["src/superfences_ps1", "tests"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.typos.default]
+extend-ignore-identifiers-re = []

superfences_ps1-0.1.0/src/superfences_ps1/__init__.py

@@ -0,0 +1,7 @@
+"""
+superfences-ps1 — MkDocs plugin that registers a SuperFences shell-prompt fence.
+
+The fence prepends a configurable prompt character to each command line so that
+Pygments emits a ``Generic.Prompt`` (``.gp``) token. Material for MkDocs strips
+``.gp`` spans from the clipboard copy, so the prompt is visible but never copied.
+"""

superfences_ps1-0.1.0/src/superfences_ps1/plugin.py

@@ -0,0 +1,163 @@
+import html
+from collections.abc import Callable
+from typing import override
+
+import markdown
+from mkdocs.config import config_options
+from mkdocs.config.base import Config
+from mkdocs.config.config_options import Optional, Type
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.exceptions import PluginError
+from mkdocs.plugins import BasePlugin, get_plugin_logger
+from mkdocs.structure.pages import Page
+from pygments import highlight
+from pygments.formatters.html import HtmlFormatter
+from pygments.lexers import get_lexer_by_name
+
+log = get_plugin_logger(__name__)
+
+DEFAULT_FENCE_NAME = "shell-ps1"
+DEFAULT_PROMPT_CHAR = "$"
+VALID_PROMPT_CHARS = ("$", "%", "#")
+
+_SUPERFENCES_KEY = "pymdownx.superfences"
+
+# Type alias for a superfences custom-fence formatter callable.
+# The signature mirrors pymdownx.superfences.fence_code_format.
+FormatterFn = Callable[..., str]
+
+# Type alias for the loosely-typed superfences configuration dicts that
+# come back from MkDocs' mdx_configs mapping (no stubs available).
+_FenceDict = dict[str, object]
+_SuperfencesCfg = dict[str, object]
+_MdxConfigs = dict[str, object]
+
+
+class ShellPromptConfig(Config):
+    fence_name: Type[str] = config_options.Type(str, default=DEFAULT_FENCE_NAME)
+    prompt_char: Type[str] = config_options.Type(str, default=DEFAULT_PROMPT_CHAR)
+    prompt_color: Optional[str] = config_options.Optional(config_options.Type(str))
+
+
+class ShellPromptPlugin(BasePlugin[ShellPromptConfig]):
+    """
+    MkDocs plugin that adds a configurable shell-prompt SuperFences fence.
+
+    The fence prepends `<prompt_char> ` to every non-empty line so that
+    Pygments' `BashSessionLexer` (`console`) emits a `Generic.Prompt`
+    token (`.gp` CSS class) for the prompt portion. A `data-copy` attribute
+    is injected on the wrapper `<div>` containing the raw (un-prompted) source
+    text so that Material for MkDocs' copy button uses that value instead of
+    reading `innerText`, keeping the prompt out of the clipboard.
+
+    Requires `pymdownx.superfences` in `markdown_extensions`.
+
+    Configuration (`mkdocs.yaml`):
+
+    ```yaml
+    plugins:
+      - superfences-ps1:
+          fence_name: shell      # fence language identifier (default: shell)
+          prompt_char: "$"       # prompt character prepended to each line (default: $)
+          prompt_color: "#89b0c2" # CSS color for the prompt character (default: unset)
+    ```
+    """
+
+    def _make_formatter(self, prompt_char: str) -> FormatterFn:
+        """Return a SuperFences-compatible formatter function for the given prompt char."""
+
+        def formatter(
+            source: str,
+            _language: str,
+            css_class: str,
+            _options: dict[str, object],
+            _md: markdown.Markdown,
+            **_kwargs: object,
+        ) -> str:
+            prompted = "\n".join(f"{prompt_char} {line}" if line.strip() else line for line in source.splitlines())
+            lexer = get_lexer_by_name("console", stripall=False)
+            fmt = HtmlFormatter(
+                cssclass=f"highlight {css_class}".strip(),
+                wrapcode=True,
+            )
+            rendered: str = highlight(prompted, lexer, fmt)
+            # Inject data-copy on the wrapper <div> with the raw (un-prompted) source
+            # text. Material for MkDocs' copy button reads this attribute in preference
+            # to innerText, so the prompt character is never included in the clipboard.
+            copy_text = html.escape(source.rstrip("\n"), quote=True)
+            return rendered.replace("<div ", f'<div data-copy="{copy_text}" ', 1)
+
+        return formatter
+
+    @override
+    def on_config(self, config: MkDocsConfig) -> MkDocsConfig | None:
+        """Inject the shell-prompt fence into the superfences custom_fences list."""
+        fence_name = self.config.fence_name
+        prompt_char = self.config.prompt_char
+
+        ext_names: set[str] = set()
+        for ext in config.get("markdown_extensions", []):
+            if isinstance(ext, str):
+                ext_names.add(ext)
+            elif isinstance(ext, dict):
+                ext_names.update(ext.keys())
+
+        if prompt_char not in VALID_PROMPT_CHARS:
+            raise PluginError(
+                f"[superfences-ps1] Invalid prompt_char {prompt_char!r}. "
+                f"Must be one of: {', '.join(repr(c) for c in VALID_PROMPT_CHARS)}. "
+                "Other characters are not recognised as prompts by Pygments' BashSessionLexer."
+            )
+
+        if _SUPERFENCES_KEY not in ext_names:
+            raise PluginError(
+                f"[superfences-ps1] '{_SUPERFENCES_KEY}' must be listed under 'markdown_extensions' in mkdocs.yaml."
+            )
+
+        mdx_configs: _MdxConfigs = config.get("mdx_configs", {})
+        superfences_cfg: _SuperfencesCfg = mdx_configs.get(_SUPERFENCES_KEY, {})
+        custom_fences: list[_FenceDict] = superfences_cfg.get("custom_fences", [])
+
+        existing_names = {f["name"] for f in custom_fences}
+        if fence_name in existing_names:
+            log.warning(
+                "Fence name '%s' is already registered in superfences; skipping injection.",
+                fence_name,
+            )
+            return None
+
+        custom_fences.append(
+            {
+                "name": fence_name,
+                "class": fence_name,
+                "format": self._make_formatter(prompt_char),
+            }
+        )
+        superfences_cfg["custom_fences"] = custom_fences
+        mdx_configs[_SUPERFENCES_KEY] = superfences_cfg
+        config["mdx_configs"] = mdx_configs
+
+        log.debug(
+            "Registered shell-prompt fence '%s' with prompt char '%s'.",
+            fence_name,
+            prompt_char,
+        )
+        return None
+
+    @override
+    def on_post_page(self, output: str, /, *, page: Page, config: MkDocsConfig) -> str:
+        """
+        Inject prompt CSS into each page's <head>.
+
+        Always injects `user-select: none` on `.gp` so the prompt character is excluded from mouse text selection.
+        Also injects a `color` rule when `prompt_color` is configured.
+        """
+        if "</head>" not in output:
+            return output
+
+        prompt_color = self.config.prompt_color
+        rules = "user-select: none;"
+        if prompt_color:
+            rules += f" color: {prompt_color};"
+        style = f"<style>.highlight .gp {{ {rules} }}</style>"
+        return output.replace("</head>", f"{style}\n</head>", 1)