mdformat-mkdocs 4.5.1__tar.gz

mdformat_mkdocs-4.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kyle King
+
+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.

mdformat_mkdocs-4.5.1/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: mdformat_mkdocs
+Version: 4.5.1
+Keywords: markdown,markdown-it,mdformat,mdformat_plugin_template
+Author: kyleking
+Author-email: kyleking <dev.act.kyle@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: mdformat>=0.7.19
+Requires-Dist: mdformat-gfm>=0.3.6
+Requires-Dist: mdit-py-plugins>=0.4.1
+Requires-Dist: more-itertools>=10.5.0
+Requires-Dist: mdformat-beautysh>=0.1.1 ; extra == 'recommended'
+Requires-Dist: mdformat-config>=0.2.1 ; extra == 'recommended'
+Requires-Dist: mdformat-footnote>=0.1.1 ; extra == 'recommended'
+Requires-Dist: mdformat-frontmatter>=2.0.8 ; extra == 'recommended'
+Requires-Dist: mdformat-gfm>=1.0.0 ; python_full_version >= '3.10' and extra == 'recommended'
+Requires-Dist: mdformat-ruff>=0.1.3 ; extra == 'recommended'
+Requires-Dist: mdformat-simple-breaks>=0.0.1 ; extra == 'recommended'
+Requires-Dist: mdformat-tables>=0.4.0 ; python_full_version < '3.10' and extra == 'recommended'
+Requires-Dist: mdformat-web>=0.2.0 ; extra == 'recommended'
+Requires-Dist: mdformat-wikilink>=0.2.0 ; extra == 'recommended'
+Requires-Dist: setuptools ; extra == 'recommended'
+Requires-Dist: beartype>=0.21.0 ; extra == 'test'
+Requires-Dist: pytest>=9.0.1 ; extra == 'test'
+Requires-Dist: pytest-beartype>=0.2.0 ; extra == 'test'
+Requires-Dist: pytest-cov>=7.0.0 ; extra == 'test'
+Requires-Dist: syrupy>=4.9.1 ; extra == 'test'
+Requires-Python: >=3.10.0
+Project-URL: Bug Tracker, https://github.com/kyleking/mdformat-mkdocs/issues
+Project-URL: Changelog, https://github.com/kyleking/mdformat-mkdocs/releases
+Project-URL: homepage, https://github.com/kyleking/mdformat-mkdocs
+Provides-Extra: recommended
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# mdformat-mkdocs
+
+[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]
+
+<!-- [![codecov.io][cov-badge]][cov-link]
+[cov-badge]: https://codecov.io/gh/executablebooks/mdformat-mkdocs/branch/main/graph/badge.svg
+[cov-link]: https://codecov.io/gh/executablebooks/mdformat-mkdocs
+ -->
+
+An [mdformat](https://github.com/executablebooks/mdformat) plugin for [mkdocs](https://github.com/mkdocs/mkdocs) and packages commonly used with MkDocs ([mkdocs-material](https://squidfunk.github.io/mkdocs-material), [mkdocstrings](https://mkdocstrings.github.io), and [python-markdown](https://python-markdown.github.io))
+
+Supports:
+
+- Indents are converted to four-spaces instead of two
+    - *Note*: when specifying `--align-semantic-breaks-in-lists`, the nested indent for ordered lists is three, but is otherwise a multiple of four
+- Unordered list bullets are converted to dashes (`-`) instead of `*`
+- By default, ordered lists are standardized on a single digit (`1.` or `0.`) unless `--number` is specified, then `mdformat-mkdocs` will apply consecutive numbering to ordered lists [for consistency with `mdformat`](https://github.com/executablebooks/mdformat?tab=readme-ov-file#options)
+- [MkDocs-Material Admonitions\*](https://squidfunk.github.io/mkdocs-material/reference/admonitions)
+    - \*Note: `mdformat-admon` will format the same admonitions, but for consistency with the mkdocs styleguide, an extra space will be added by this package ([#22](https://github.com/KyleKing/mdformat-admon/pull/22))
+- [MkDocs-Material Content Tabs\*](https://squidfunk.github.io/mkdocs-material/reference/content-tabs)
+    - \*Note: the markup (HTML) rendered by this plugin is sufficient for formatting but not for viewing in a browser. Please open an issue if you have a need to generate valid HTML.
+- [MkDocs-Material Definition Lists](https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists)
+- [mkdocstrings Anchors (autorefs)](https://mkdocstrings.github.io/autorefs/#markdown-anchors)
+- [mkdocstrings Cross-References](https://mkdocstrings.github.io/usage/#cross-references)
+- [Python Markdown "Abbreviations"\*](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations)
+    - \*Note: the markup (HTML) rendered for abbreviations is not useful for rendering. If important, I'm open to contributions because the implementation could be challenging
+- [Python Markdown "Snippets"\*](https://facelessuser.github.io/pymdown-extensions/extensions/snippets)
+    - \*Note: the markup (HTML) renders the plain text without implementing the snippet logic. I'm open to contributions if anyone needs full support for snippets
+
+See the example test files, [./tests/pre-commit-test.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/pre-commit-test.md) and [./tests/format/fixtures.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/format/fixtures.md)
+
+## `mdformat` Usage
+
+Add this package wherever you use `mdformat` and the plugin will be auto-recognized. No additional configuration necessary. For additional information on plugins, see [the official `mdformat` documentation here](https://mdformat.readthedocs.io/en/stable/users/plugins.html)
+
+**Tip**: this package specifies an "extra" (`'recommended'`) for plugins that work well with typical documentation managed by `mkdocs`:
+
+- [mdformat-beautysh](https://pypi.org/project/mdformat-beautysh)
+- [mdformat-black](https://pypi.org/project/mdformat-black)
+- [mdformat-config](https://pypi.org/project/mdformat-config)
+- [mdformat-footnote](https://pypi.org/project/mdformat-footnote)
+- [mdformat-frontmatter](https://pypi.org/project/mdformat-frontmatter)
+- [mdformat-simple-breaks](https://pypi.org/project/mdformat-simple-breaks)
+- [mdformat-web](https://pypi.org/project/mdformat-web)
+- [mdformat-wikilink](https://github.com/tmr232/mdformat-wikilink)
+
+### pre-commit/prek
+
+```yaml
+repos:
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.19
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-mkdocs
+          # Or
+          # - "mdformat-mkdocs[recommended]"
+```
+
+### pipx/uv
+
+```sh
+pipx install mdformat
+pipx inject mdformat mdformat-mkdocs
+```
+
+Or with uv:
+
+```sh
+uv tool run --from mdformat-mkdocs mdformat
+```
+
+## HTML Rendering
+
+To generate HTML output, any of the plugins can be imported from `mdit_plugins`. For more guidance on `MarkdownIt`, see the docs: <https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser>
+
+```py
+from markdown_it import MarkdownIt
+
+from mdformat_mkdocs.mdit_plugins import (
+    material_admon_plugin,
+    material_content_tabs_plugin,
+    mkdocstrings_autorefs_plugin,
+    mkdocstrings_crossreference_plugin,
+    pymd_abbreviations_plugin,
+)
+
+md = MarkdownIt()
+md.use(material_admon_plugin)
+md.use(material_content_tabs_plugin)
+md.use(mkdocstrings_autorefs_plugin)
+md.use(mkdocstrings_crossreference_plugin)
+md.use(pymd_abbreviations_plugin)
+
+text = "- Line 1\n    - `bash command`\n    - Line 3"
+md.render(text)
+# <ul>
+# <li>Line 1
+# <ul>
+# <li><code>bash command</code></li>
+# <li>Line 3</li>
+# </ul>
+# </li>
+# </ul>
+```
+
+## Configuration
+
+`mdformat-mkdocs` adds the CLI arguments:
+
+- `--align-semantic-breaks-in-lists` to optionally align line breaks in numbered lists to 3-spaces. If not specified, the default of 4-indents is followed universally.
+
+    ```txt
+    # with: mdformat
+    1. Semantic line feed where the following line is
+        three spaces deep
+
+    # vs. "mdformat --align-semantic-breaks-in-lists"
+    1. Semantic line feed where the following line is
+       three spaces deep
+    ```
+
+- `--ignore-missing-references` if set, do not escape link references when no definition is found. This is required when references are dynamic, such as with python mkdocstrings
+
+You can also use the toml configuration (https://mdformat.readthedocs.io/en/stable/users/configuration_file.html):
+
+```toml
+# .mdformat.toml
+
+[plugin.mkdocs]
+align_semantic_breaks_in_lists = true
+ignore_missing_references = true
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/kyleking/mdformat-mkdocs/blob/main/CONTRIBUTING.md)
+
+[ci-badge]: https://github.com/kyleking/mdformat-mkdocs/workflows/CI/badge.svg?branch=main
+[ci-link]: https://github.com/kyleking/mdformat-mkdocs/actions?query=workflow%3ACI+branch%3Amain+event%3Apush
+[pypi-badge]: https://img.shields.io/pypi/v/mdformat-mkdocs.svg
+[pypi-link]: https://pypi.org/project/mdformat-mkdocs

mdformat_mkdocs-4.5.1/README.md

@@ -0,0 +1,143 @@
+# mdformat-mkdocs
+
+[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]
+
+<!-- [![codecov.io][cov-badge]][cov-link]
+[cov-badge]: https://codecov.io/gh/executablebooks/mdformat-mkdocs/branch/main/graph/badge.svg
+[cov-link]: https://codecov.io/gh/executablebooks/mdformat-mkdocs
+ -->
+
+An [mdformat](https://github.com/executablebooks/mdformat) plugin for [mkdocs](https://github.com/mkdocs/mkdocs) and packages commonly used with MkDocs ([mkdocs-material](https://squidfunk.github.io/mkdocs-material), [mkdocstrings](https://mkdocstrings.github.io), and [python-markdown](https://python-markdown.github.io))
+
+Supports:
+
+- Indents are converted to four-spaces instead of two
+    - *Note*: when specifying `--align-semantic-breaks-in-lists`, the nested indent for ordered lists is three, but is otherwise a multiple of four
+- Unordered list bullets are converted to dashes (`-`) instead of `*`
+- By default, ordered lists are standardized on a single digit (`1.` or `0.`) unless `--number` is specified, then `mdformat-mkdocs` will apply consecutive numbering to ordered lists [for consistency with `mdformat`](https://github.com/executablebooks/mdformat?tab=readme-ov-file#options)
+- [MkDocs-Material Admonitions\*](https://squidfunk.github.io/mkdocs-material/reference/admonitions)
+    - \*Note: `mdformat-admon` will format the same admonitions, but for consistency with the mkdocs styleguide, an extra space will be added by this package ([#22](https://github.com/KyleKing/mdformat-admon/pull/22))
+- [MkDocs-Material Content Tabs\*](https://squidfunk.github.io/mkdocs-material/reference/content-tabs)
+    - \*Note: the markup (HTML) rendered by this plugin is sufficient for formatting but not for viewing in a browser. Please open an issue if you have a need to generate valid HTML.
+- [MkDocs-Material Definition Lists](https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists)
+- [mkdocstrings Anchors (autorefs)](https://mkdocstrings.github.io/autorefs/#markdown-anchors)
+- [mkdocstrings Cross-References](https://mkdocstrings.github.io/usage/#cross-references)
+- [Python Markdown "Abbreviations"\*](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations)
+    - \*Note: the markup (HTML) rendered for abbreviations is not useful for rendering. If important, I'm open to contributions because the implementation could be challenging
+- [Python Markdown "Snippets"\*](https://facelessuser.github.io/pymdown-extensions/extensions/snippets)
+    - \*Note: the markup (HTML) renders the plain text without implementing the snippet logic. I'm open to contributions if anyone needs full support for snippets
+
+See the example test files, [./tests/pre-commit-test.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/pre-commit-test.md) and [./tests/format/fixtures.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/format/fixtures.md)
+
+## `mdformat` Usage
+
+Add this package wherever you use `mdformat` and the plugin will be auto-recognized. No additional configuration necessary. For additional information on plugins, see [the official `mdformat` documentation here](https://mdformat.readthedocs.io/en/stable/users/plugins.html)
+
+**Tip**: this package specifies an "extra" (`'recommended'`) for plugins that work well with typical documentation managed by `mkdocs`:
+
+- [mdformat-beautysh](https://pypi.org/project/mdformat-beautysh)
+- [mdformat-black](https://pypi.org/project/mdformat-black)
+- [mdformat-config](https://pypi.org/project/mdformat-config)
+- [mdformat-footnote](https://pypi.org/project/mdformat-footnote)
+- [mdformat-frontmatter](https://pypi.org/project/mdformat-frontmatter)
+- [mdformat-simple-breaks](https://pypi.org/project/mdformat-simple-breaks)
+- [mdformat-web](https://pypi.org/project/mdformat-web)
+- [mdformat-wikilink](https://github.com/tmr232/mdformat-wikilink)
+
+### pre-commit/prek
+
+```yaml
+repos:
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.19
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-mkdocs
+          # Or
+          # - "mdformat-mkdocs[recommended]"
+```
+
+### pipx/uv
+
+```sh
+pipx install mdformat
+pipx inject mdformat mdformat-mkdocs
+```
+
+Or with uv:
+
+```sh
+uv tool run --from mdformat-mkdocs mdformat
+```
+
+## HTML Rendering
+
+To generate HTML output, any of the plugins can be imported from `mdit_plugins`. For more guidance on `MarkdownIt`, see the docs: <https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser>
+
+```py
+from markdown_it import MarkdownIt
+
+from mdformat_mkdocs.mdit_plugins import (
+    material_admon_plugin,
+    material_content_tabs_plugin,
+    mkdocstrings_autorefs_plugin,
+    mkdocstrings_crossreference_plugin,
+    pymd_abbreviations_plugin,
+)
+
+md = MarkdownIt()
+md.use(material_admon_plugin)
+md.use(material_content_tabs_plugin)
+md.use(mkdocstrings_autorefs_plugin)
+md.use(mkdocstrings_crossreference_plugin)
+md.use(pymd_abbreviations_plugin)
+
+text = "- Line 1\n    - `bash command`\n    - Line 3"
+md.render(text)
+# <ul>
+# <li>Line 1
+# <ul>
+# <li><code>bash command</code></li>
+# <li>Line 3</li>
+# </ul>
+# </li>
+# </ul>
+```
+
+## Configuration
+
+`mdformat-mkdocs` adds the CLI arguments:
+
+- `--align-semantic-breaks-in-lists` to optionally align line breaks in numbered lists to 3-spaces. If not specified, the default of 4-indents is followed universally.
+
+    ```txt
+    # with: mdformat
+    1. Semantic line feed where the following line is
+        three spaces deep
+
+    # vs. "mdformat --align-semantic-breaks-in-lists"
+    1. Semantic line feed where the following line is
+       three spaces deep
+    ```
+
+- `--ignore-missing-references` if set, do not escape link references when no definition is found. This is required when references are dynamic, such as with python mkdocstrings
+
+You can also use the toml configuration (https://mdformat.readthedocs.io/en/stable/users/configuration_file.html):
+
+```toml
+# .mdformat.toml
+
+[plugin.mkdocs]
+align_semantic_breaks_in_lists = true
+ignore_missing_references = true
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/kyleking/mdformat-mkdocs/blob/main/CONTRIBUTING.md)
+
+[ci-badge]: https://github.com/kyleking/mdformat-mkdocs/workflows/CI/badge.svg?branch=main
+[ci-link]: https://github.com/kyleking/mdformat-mkdocs/actions?query=workflow%3ACI+branch%3Amain+event%3Apush
+[pypi-badge]: https://img.shields.io/pypi/v/mdformat-mkdocs.svg
+[pypi-link]: https://pypi.org/project/mdformat-mkdocs

mdformat_mkdocs-4.5.1/mdformat_mkdocs/__init__.py

@@ -0,0 +1,11 @@
+"""An mdformat plugin for `mkdocs`."""
+
+__version__ = "4.5.1"
+
+__plugin_name__ = "mkdocs"
+
+# FYI see source code for available interfaces:
+#   https://github.com/executablebooks/mdformat/blob/5d9b573ce33bae219087984dd148894c774f41d4/src/mdformat/plugins.py
+from .plugin import POSTPROCESSORS, RENDERERS, add_cli_argument_group, update_mdit
+
+__all__ = ("POSTPROCESSORS", "RENDERERS", "add_cli_argument_group", "update_mdit")

mdformat_mkdocs-4.5.1/mdformat_mkdocs/_helpers.py

@@ -0,0 +1,59 @@
+"""General Helpers."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from functools import wraps
+from typing import Any
+
+from . import __plugin_name__
+
+EOL = "\n"
+"""Line delimiter."""
+
+MKDOCS_INDENT_COUNT = 4
+"""Use 4-spaces for mkdocs."""
+
+FILLER_CHAR = "𝕏"  # noqa: RUF001
+"""A spacer that is inserted and then removed to ensure proper word wrap."""
+
+
+def rstrip_result(func: Callable[..., str]) -> Callable[..., str]:
+    """Right-strip the decorated function's result.
+
+    Returns:
+        Callable[..., str]: decorator
+
+    """
+
+    @wraps(func)
+    def _wrapper(*args, **kwargs) -> str:
+        return func(*args, **kwargs).rstrip()
+
+    return _wrapper
+
+
+def separate_indent(line: str) -> tuple[str, str]:
+    """Separate leading indent from content. Also used by the test suite.
+
+    Returns:
+        tuple[str, str]: separate indent and content
+
+    """
+    re_indent = re.compile(r"(?P<indent>\s*)(?P<content>[^\s]?.*)")
+    match = re_indent.match(line)
+    assert match  # for pyright
+    return (match["indent"], match["content"])
+
+
+ContextOptions = Mapping[str, Any]
+
+
+def get_conf(options: ContextOptions, key: str) -> bool | str | int | None:
+    """Read setting from mdformat configuration Context."""
+    if (api := options["mdformat"].get(key)) is not None:
+        return api  # From API
+    return (
+        options["mdformat"].get("plugin", {}).get(__plugin_name__, {}).get(key)
+    )  # from cli_or_toml