mdit-py-plugins 0.5.0__tar.gz → 0.6.1__tar.gz

mdit_py_plugins-0.6.1/.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,43 @@
+name: Copilot Setup Steps
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      contents: read
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+        cache: pip
+
+    - name: Install uv
+      run: pip install uv
+
+    - name: Install pre-commit and pre-commit-uv
+      run: pip install pre-commit pre-commit-uv
+
+    - name: Install tox and tox-uv
+      run: pip install tox tox-uv

{mdit_py_plugins-0.5.0 → mdit_py_plugins-0.6.1}/.pre-commit-config.yaml

@@ -20,14 +20,14 @@ repos:
     - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.8
+    rev: v0.15.12
     hooks:
     - id: ruff
       args: [--fix]
     - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.17.1
+    rev: v1.20.2
     hooks:
     - id: mypy
       additional_dependencies: [markdown-it-py~=3.0]

mdit_py_plugins-0.6.1/AGENTS.md

@@ -0,0 +1,373 @@
+# AGENTS.md
+
+This file provides guidance for AI coding agents working on the **mdit-py-plugins** repository.
+
+## Project Overview
+
+mdit-py-plugins is a collection of plugins for [markdown-it-py](https://github.com/executablebooks/markdown-it-py), the Python Markdown parser. It provides:
+
+- Syntax extensions for markdown-it-py (footnotes, front matter, definition lists, task lists, etc.)
+- Both block-level and inline-level parsing rules
+- Each plugin follows the markdown-it-py plugin architecture: a function that receives a `MarkdownIt` instance and registers rules
+- Used extensively by [MyST-Parser](https://github.com/executablebooks/MyST-Parser) for Sphinx documentation
+
+## Repository Structure
+
+```
+pyproject.toml          # Project configuration and dependencies (flit)
+tox.ini                 # Tox test environment configuration
+.pre-commit-config.yaml # Pre-commit hooks configuration
+
+mdit_py_plugins/        # Main source code
+├── __init__.py         # Package init (version only)
+├── utils.py            # Shared utility functions
+├── py.typed            # PEP 561 marker
+├── admon/              # Admonition plugin (note, warning, etc.)
+├── amsmath/            # AMS math environment plugin
+├── anchors/            # Heading anchor plugin
+├── attrs/              # Inline/block attribute plugin ({.class #id})
+├── colon_fence.py      # Colon fence plugin (:::)
+├── container/          # Container plugin (custom divs)
+├── deflist/            # Definition list plugin
+├── dollarmath/         # Dollar math plugin ($...$, $$...$$)
+├── field_list/         # Field list plugin
+├── footnote/           # Footnote plugin
+├── front_matter/       # YAML front matter plugin
+├── myst_blocks/        # MyST block syntax plugin
+├── myst_role/          # MyST role syntax plugin ({role}`text`)
+├── subscript/          # Subscript plugin (~sub~)
+├── substitution.py     # Substitution plugin
+├── tasklists/          # Task list plugin (- [x] done)
+├── texmath/            # TeX math plugin
+└── wordcount/          # Word count plugin
+
+tests/                  # Test suite
+├── fixtures/           # Shared test fixture files
+├── test_admon/         # Admonition tests with fixture files
+├── test_amsmath/       # AMS math tests
+├── test_anchors.py     # Anchors tests
+├── test_attrs/         # Attributes tests
+├── test_colon_fence/   # Colon fence tests
+├── test_container/     # Container tests
+├── test_deflist/       # Definition list tests
+├── test_dollarmath/    # Dollar math tests
+├── test_field_list/    # Field list tests
+├── test_footnote.py    # Footnote tests
+├── test_front_matter.py # Front matter tests
+├── test_myst_block.py  # MyST block tests
+├── test_myst_role.py   # MyST role tests
+├── test_subscript.py   # Subscript tests
+├── test_substitution/  # Substitution tests
+├── test_tasklists/     # Task list tests
+├── test_texmath/       # TeX math tests
+└── test_wordcount.py   # Word count tests
+
+docs/                   # Documentation source
+├── conf.py             # Sphinx configuration
+└── index.md            # Documentation index
+```
+
+## Development Commands
+
+All commands should be run via [`tox`](https://tox.wiki) for consistency. The project uses `tox-uv` for faster environment creation.
+
+### Testing
+
+```bash
+# Run all tests
+tox
+
+# Run tests with specific Python version
+tox -e py311
+
+# Run a specific test file
+tox -e py310 -- tests/test_footnote.py
+
+# Run a specific test function
+tox -e py310 -- tests/test_footnote.py::test_function_name
+
+# Run tests with coverage
+tox -e py310 -- --cov=mdit_py_plugins --cov-report=html
+
+# Update regression test fixtures (produces error if files change)
+tox -e py310 -- --force-regen
+```
+
+### Documentation
+
+```bash
+# Build docs (clean)
+tox -e docs-clean
+
+# Build docs (incremental)
+tox -e docs-update
+
+# Build with a specific builder (e.g., linkcheck to validate external links)
+tox -e docs-update -- linkcheck
+```
+
+### Code Quality
+
+```bash
+# Run all pre-commit hooks (ruff, mypy, trailing whitespace, etc.)
+tox -e pre-commit
+
+# Run pre-commit with specific hook
+tox -e pre-commit -- --all-files ruff
+
+# Run mypy type checking
+tox -e mypy
+
+# Run pre-commit hooks directly (if pre-commit is installed)
+pre-commit run --all-files
+```
+
+## Code Style Guidelines
+
+- **Formatter/Linter**: Ruff (configured in `pyproject.toml`)
+- **Type Checking**: Mypy with strict settings (configured in `pyproject.toml`)
+- **Pre-commit**: Use pre-commit hooks for consistent code style
+
+### Best Practices
+
+- **Type annotations**: Use complete type annotations for all function signatures.
+- **Docstrings**: Include docstrings for public functions and classes.
+- **Pure functions**: Where possible, write pure functions without side effects.
+- Follow existing naming conventions (`N802`, `N803`, `N806` are excluded to match markdown-it naming).
+
+## Testing Guidelines
+
+- **Framework**: pytest with `pytest-regressions` for fixture-based tests
+- **Fixture pattern**: Most plugins use `.md` fixture files containing input and expected HTML output, separated by `.` markers
+- **Test location**: Each plugin has a corresponding test file or directory in `tests/`
+- **Regression tests**: Use `pytest-regressions` for comparing rendered output against stored fixtures
+
+### Fixture File Format
+
+Fixture files (`.md` files in test directories) use a specific format:
+
+```markdown
+Plugin Name
+.
+markdown input
+.
+expected html output
+.
+
+Another Test Case
+.
+more markdown input
+.
+more expected html output
+.
+```
+
+### Running Specific Tests
+
+```bash
+# Test a single plugin
+tox -e py310 -- tests/test_dollarmath.py
+
+# Verbose output with full tracebacks
+tox -e py310 -- -v --tb=long tests/test_footnote.py
+```
+
+## Architecture
+
+### Plugin Structure
+
+Each plugin follows the markdown-it-py plugin pattern:
+
+```python
+from markdown_it import MarkdownIt
+
+
+def my_plugin(md: MarkdownIt, **options: ...) -> None:
+    """My custom plugin description."""
+    # Register block rules
+    md.block.ruler.before("fence", "my_block_rule", my_block_rule)
+
+    # Register inline rules
+    md.inline.ruler.after("emphasis", "my_inline_rule", my_inline_rule)
+
+    # Add render rules
+    md.add_render_rule("my_token_type", render_my_token)
+```
+
+### Plugin Types
+
+1. **Block plugins** (e.g., `amsmath`, `container`, `deflist`, `front_matter`): Parse block-level syntax using `StateBlock`
+2. **Inline plugins** (e.g., `dollarmath`, `myst_role`, `subscript`): Parse inline syntax using `StateInline`
+3. **Core plugins** (e.g., `footnote`, `wordcount`): Operate on the full token stream in a post-processing step
+4. **Single-file plugins** (e.g., `colon_fence.py`, `substitution.py`): Simple plugins in a single module
+5. **Multi-file plugins** (e.g., `footnote/`, `dollarmath/`): More complex plugins with `__init__.py` and `index.py`
+
+### Multi-file Plugin Layout
+
+```
+plugin_name/
+├── __init__.py   # Exports the plugin function (e.g., dollarmath_plugin)
+└── index.py      # Contains the implementation (rule functions, renderers)
+```
+
+### Token Flow
+
+Plugins create and manipulate markdown-it tokens:
+
+```python
+token = state.push("my_type_open", "div", 1)   # Opening tag
+token.attrSet("class", "my-class")
+token.markup = "..."
+token.map = [startLine, nextLine]
+
+# Content tokens...
+
+token = state.push("my_type_close", "div", -1)  # Closing tag
+```
+
+## Commit Message Format
+
+Use this format:
+
+```
+<EMOJI> <KEYWORD>: Summarize in 72 chars or less (#<PR>)
+
+Optional detailed explanation.
+```
+
+Keywords:
+
+- `✨ NEW:` – New feature
+- `🐛 FIX:` – Bug fix
+- `👌 IMPROVE:` – Improvement (no breaking changes)
+- `‼️ BREAKING:` – Breaking change
+- `📚 DOCS:` – Documentation
+- `🔧 MAINTAIN:` – Maintenance changes only (typos, etc.)
+- `🧪 TEST:` – Tests or CI changes only
+- `♻️ REFACTOR:` – Refactoring
+
+## Pull Request Requirements
+
+When submitting changes:
+
+1. **Description**: Include a meaningful description or link explaining the change
+2. **Tests**: Include test cases for new functionality or bug fixes
+3. **Documentation**: Update docs if behavior changes or new features are added
+4. **Changelog**: Update `CHANGELOG.md` under the appropriate section
+5. **Code Quality**: Ensure `pre-commit run --all-files` passes
+6. **Type Checking**: Ensure mypy passes with strict settings
+
+## Key Files
+
+- `pyproject.toml` - Project configuration, dependencies, and tool settings (Ruff, Mypy)
+- `tox.ini` - Test environment configuration
+- `mdit_py_plugins/__init__.py` - Package version
+- `mdit_py_plugins/utils.py` - Shared utilities (e.g., `is_code_block`)
+- `CHANGELOG.md` - Change log for releases
+
+## Debugging
+
+- Use `md.parse(text)` to inspect the token stream produced by plugins
+- Use `md.render(text)` to see final HTML output
+- Enable/disable specific plugins using `md.use()` / `md.disable()`
+- Use `tox -- -v --tb=long` for verbose test output with full tracebacks
+
+### Debugging Tips
+
+```python
+from markdown_it import MarkdownIt
+
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+
+md = MarkdownIt().use(dollarmath_plugin)
+
+# See the token stream
+tokens = md.parse("Some $inline$ math and $$block$$ math")
+for token in tokens:
+    print(f"{token.type} | {token.tag} | {token.content}")
+    if token.children:
+        for child in token.children:
+            print(f"  {child.type} | {child.tag} | {child.content}")
+
+# See rendered HTML
+print(md.render("Some $inline$ math"))
+```
+
+## Common Patterns
+
+### Adding a New Plugin
+
+1. Create a new directory under `mdit_py_plugins/` (or a single `.py` file for simple plugins)
+2. Implement the plugin function following the standard pattern:
+   ```python
+   from markdown_it import MarkdownIt
+
+   def my_plugin(md: MarkdownIt) -> None:
+       md.block.ruler.before("fence", "my_rule", _my_rule)
+       md.add_render_rule("my_type", _render_my_type)
+   ```
+3. Export the plugin function from `__init__.py`
+4. Add test fixtures in `tests/test_my_plugin/`
+5. Add a test file `tests/test_my_plugin.py`
+6. Update `CHANGELOG.md`
+
+### Adding a Block Rule
+
+Block rules receive `(state: StateBlock, startLine: int, endLine: int, silent: bool) -> bool`:
+
+```python
+from markdown_it.rules_block import StateBlock
+
+def my_block_rule(
+    state: StateBlock, startLine: int, endLine: int, silent: bool
+) -> bool:
+    # Check if this line matches your syntax
+    pos = state.bMarks[startLine] + state.tShift[startLine]
+    maximum = state.eMarks[startLine]
+
+    if state.src[pos] != "$":
+        return False
+
+    # In silent mode, just return True if matched (used for validation)
+    if silent:
+        return True
+
+    # Parse content and create tokens
+    token = state.push("my_type", "", 0)
+    token.content = ...
+    token.map = [startLine, nextLine]
+
+    state.line = nextLine
+    return True
+```
+
+### Adding an Inline Rule
+
+Inline rules receive `(state: StateInline, silent: bool) -> bool`:
+
+```python
+from markdown_it.rules_inline import StateInline
+
+def my_inline_rule(state: StateInline, silent: bool) -> bool:
+    if state.src[state.pos] != "$":
+        return False
+
+    # Parse and validate
+    ...
+
+    if not silent:
+        token = state.push("my_type", "", 0)
+        token.content = content
+
+    state.pos = end
+    return True
+```
+
+## Reference Documentation
+
+- [markdown-it-py Documentation](https://markdown-it-py.readthedocs.io/)
+- [markdown-it-py Repository](https://github.com/executablebooks/markdown-it-py)
+- [mdit-py-plugins Documentation](https://mdit-py-plugins.readthedocs.io/)
+- [Original markdown-it (JavaScript)](https://github.com/markdown-it/markdown-it)
+- [CommonMark Spec](https://spec.commonmark.org/)
+- [MyST-Parser Repository](https://github.com/executablebooks/MyST-Parser)

{mdit_py_plugins-0.5.0 → mdit_py_plugins-0.6.1}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Change Log
 
+## 0.6.1 - 2026-05-13
+
+- 🐛 FIX: Nested field lists incorrectly nesting inside parent containers (#139)
+
+  Field lists inside list items (or other indented containers) would recursively nest each field inside the previous one, instead of being siblings.
+
+## 0.6.0 - 2026-05-07
+
+- ✨ NEW: Add GFM autolink and composite GFM plugins (#135)
+
+  The `gfm_autolink` plugin implements [GFM autolink literals](https://github.github.com/gfm/#autolinks-extension-),
+  auto-linking URLs and email addresses without requiring angle brackets:
+
+  ```markdown
+  Visit www.example.com or contact user@example.com
+  ```
+
+  The `gfm` composite plugin enables a full Github Flavored Markdown (GFM)-like configuration in a single call
+  (tables, strikethrough, autolinks, task lists, alerts, and footnotes).
+
+  See [the GitHub docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for more information.
+
+  **Requires markdown-it-py >= 4.1.0.**
+
+- ✨ NEW: Add superscript plugin and tests, thanks to @elijahgreenstein (#128)
+
+  Ported from [markdown-it-sup](https://github.com/markdown-it/markdown-it-sup).
+  Renders superscript text using `^..^` syntax:
+
+  ```markdown
+  29^th^ of May
+  ```
+
 ## 0.5.0 - 2025-08-11
 
 - ⬆️ Drop Python 3.9, which is EoL next month <https://devguide.python.org/versions> and allow for the, soon to be released, markdown-it-py v4.

{mdit_py_plugins-0.5.0 → mdit_py_plugins-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdit-py-plugins
-Version: 0.5.0
+Version: 0.6.1
 Summary: Collection of plugins for markdown-it-py
 Keywords: markdown,markdown-it,lexer,parser,development
 Author-email: Chris Sewell <chrisj_sewell@hotmail.com>
@@ -28,6 +28,7 @@ Requires-Dist: coverage ; extra == "testing"
 Requires-Dist: pytest ; extra == "testing"
 Requires-Dist: pytest-cov ; extra == "testing"
 Requires-Dist: pytest-regressions ; extra == "testing"
+Requires-Dist: pytest-timeout ; extra == "testing"
 Project-URL: Documentation, https://mdit-py-plugins.readthedocs.io
 Project-URL: Homepage, https://github.com/executablebooks/mdit-py-plugins
 Provides-Extra: code-style

mdit_py_plugins-0.6.1/mdit_py_plugins/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.1"

{mdit_py_plugins-0.5.0 → mdit_py_plugins-0.6.1}/mdit_py_plugins/attrs/index.py

@@ -209,7 +209,7 @@ def _attr_block_rule(
         return False
 
     try:
-        new_pos, attrs = parse(state.src[pos:maximum])
+        _new_pos, attrs = parse(state.src[pos:maximum])
     except ParseError:
         return False
 

{mdit_py_plugins-0.5.0 → mdit_py_plugins-0.6.1}/mdit_py_plugins/dollarmath/index.py

@@ -78,7 +78,9 @@ def dollarmath_plugin(
     _label_renderer: Callable[[str], str]
     if label_renderer is None:
         _label_renderer = (  # noqa: E731
-            lambda label: f'<a href="#{label}" class="mathlabel" title="Permalink to this equation">¶</a>'
+            lambda label: (
+                f'<a href="#{label}" class="mathlabel" title="Permalink to this equation">¶</a>'
+            )
         )
     else:
         _label_renderer = label_renderer

{mdit_py_plugins-0.5.0 → mdit_py_plugins-0.6.1}/mdit_py_plugins/field_list/__init__.py

@@ -164,8 +164,9 @@ def _fieldlist_rule(
             while _line < endLine:
                 # if start_of_content < end_of_content, then non-empty line
                 if (state.bMarks[_line] + state.tShift[_line]) < state.eMarks[_line]:
-                    if state.tShift[_line] <= 0:
-                        # the line has no indent, so it's the end of the field
+                    if state.tShift[_line] <= state.blkIndent:
+                        # the line is not indented relative to the field marker,
+                        # so it's the end of the field body
                         break
                     block_indent = (
                         state.tShift[_line]

mdit_py_plugins-0.6.1/mdit_py_plugins/gfm/__init__.py

@@ -0,0 +1,102 @@
+"""Composite GFM (GitHub Flavored Markdown) plugin.
+
+Enables a set of plugins that together approximate GitHub's Markdown rendering:
+
+- Tables (built-in)
+- Strikethrough with single and double tildes (built-in)
+- Autolinks (gfm_autolink plugin)
+- Task lists (built-in, markdown-it-py >= 4.1.0)
+- Alerts (built-in, markdown-it-py >= 4.1.0)
+- Footnotes (``[^label]`` references and definitions)
+
+Optional extras:
+
+- Dollar math (``$...$`` / ``$$...$$``)
+- Front matter (YAML)
+
+.. note::
+   Tag filtering (disallowed raw HTML tags) is not yet implemented.
+
+.. seealso::
+   - `GitHub Flavored Markdown Spec <https://github.github.com/gfm/>`__
+   - `GitHub basic formatting syntax
+     <https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax>`__
+
+.. versionadded:: 0.5.0
+
+Requires markdown-it-py >= 4.1.0.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from markdown_it import MarkdownIt
+from markdown_it import __version__ as _mdit_version
+
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+from mdit_py_plugins.footnote import footnote_plugin
+from mdit_py_plugins.front_matter import front_matter_plugin
+from mdit_py_plugins.gfm_autolink import gfm_autolink_plugin
+
+__all__ = ("gfm_plugin",)
+
+_MIN_VERSION = (4, 1, 0)
+
+
+@lru_cache(maxsize=8)
+def _parse_version(v: str) -> tuple[int, ...]:
+    """Parse a version string like '4.1.0' into a tuple of ints."""
+    return tuple(int(x) for x in v.split(".")[:3])
+
+
+def gfm_plugin(
+    md: MarkdownIt,
+    *,
+    dollarmath: bool = False,
+    front_matter: bool = False,
+    tasklists_editable: bool = False,
+) -> None:
+    """Enable GFM-like rendering.
+
+    Starts from the current parser configuration and enables the GFM
+    components on top.
+
+    :param dollarmath: Enable dollar-delimited math (``$...$``, ``$$...$$``).
+    :param front_matter: Enable YAML front matter (``---``).
+    :param tasklists_editable: If True, rendered task list checkboxes are not
+        disabled (i.e. they are interactive).
+    """
+    if _parse_version(_mdit_version) < _MIN_VERSION:
+        raise RuntimeError(
+            f"gfm_plugin requires markdown-it-py >= {'.'.join(str(x) for x in _MIN_VERSION)} "
+            f"(installed: {_mdit_version})"
+        )
+
+    # Enable table and strikethrough rules (built into markdown-it-py)
+    md.enable("table")
+    md.enable("strikethrough")
+
+    # GFM options available in markdown-it-py >= 4.1.0
+    md.options["tasklists"] = True
+    md.options["tasklists_editable"] = tasklists_editable
+    md.options["alerts"] = True
+    md.options["strikethrough_single_tilde"] = True
+    # GFM autolinks
+    md.use(gfm_autolink_plugin)
+
+    # Footnotes (inline footnotes ^[...] are not part of GFM)
+    md.use(footnote_plugin, inline=False)
+
+    # Dollar math (inline $...$ and block $$...$$)
+    if dollarmath:
+        md.use(dollarmath_plugin, allow_blank_lines=False)
+
+    # TODO: Tag filter — replace leading `<` with `&lt;` for disallowed raw
+    # HTML tags: <title>, <textarea>, <style>, <xmp>, <iframe>, <noembed>,
+    # <noframes>, <script>, <plaintext>.
+    # See https://github.github.com/gfm/#disallowed-raw-html-extension-
+
+    # Optional plugins
+    if front_matter:
+        md.use(front_matter_plugin)

mdit_py_plugins-0.6.1/mdit_py_plugins/gfm_autolink/__init__.py

@@ -0,0 +1,15 @@
+"""GFM autolink extension plugin for markdown-it-py.
+
+Implements the `GFM autolink extension
+<https://github.github.com/gfm/#autolinks-extension->`_,
+which recognises bare URLs (``http://``, ``https://``, ``www.``),
+protocol links (``mailto:``, ``xmpp:``),
+and bare email addresses without requiring angle brackets.
+
+Ported from the Rust crate
+`markdown_it_autolink <https://github.com/markdown-it-rust/markdown-it-plugins.rs>`_.
+"""
+
+from .index import gfm_autolink_plugin
+
+__all__ = ("gfm_autolink_plugin",)