diff --git a/README.md b/README.md index 9b54e88..c8cf657 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,16 @@ Supports: - *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) +- [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. - [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) diff --git a/mdformat_mkdocs/mdit_plugins/__init__.py b/mdformat_mkdocs/mdit_plugins/__init__.py index 565d1d9..2fec958 100644 --- a/mdformat_mkdocs/mdit_plugins/__init__.py +++ b/mdformat_mkdocs/mdit_plugins/__init__.py @@ -15,6 +15,7 @@ mkdocstrings_crossreference_plugin, ) from ._pymd_abbreviations import PYMD_ABBREVIATIONS_PREFIX, pymd_abbreviations_plugin +from ._pymd_snippet import PYMD_SNIPPET_PREFIX, pymd_snippet_plugin from ._python_markdown_admon import python_markdown_admon_plugin __all__ = ( @@ -24,10 +25,12 @@ "MKDOCSTRINGS_CROSSREFERENCE_PREFIX", "MKDOCSTRINGS_HEADING_AUTOREFS_PREFIX", "PYMD_ABBREVIATIONS_PREFIX", + "PYMD_SNIPPET_PREFIX", "material_admon_plugin", "material_content_tabs_plugin", "mkdocstrings_autorefs_plugin", "mkdocstrings_crossreference_plugin", "pymd_abbreviations_plugin", + "pymd_snippet_plugin", "python_markdown_admon_plugin", ) diff --git a/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py new file mode 100644 index 0000000..f70f1e2 --- /dev/null +++ b/mdformat_mkdocs/mdit_plugins/_pymd_snippet.py @@ -0,0 +1,100 @@ +"""Python-Markdown Snippets. + +WARNING: matches only the "scissors" portion, leaving the rest unparsed + +```md +--8<-- ... +``` + +Docs: + +""" + +from __future__ import annotations + +import re + +from markdown_it import MarkdownIt +from markdown_it.rules_block import StateBlock +from mdit_py_plugins.utils import is_code_block + +from mdformat_mkdocs._synced.admon_factories import new_token + +_SNIPPET_MARKER = "--8<--" +_ABBREVIATION_PATTERN = re.compile(rf"^{_SNIPPET_MARKER}(?P