# 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.
- [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-tables](https://pypi.org/project/mdformat-tables)
- [mdformat-web](https://pypi.org/project/mdformat-web)
- [mdformat-wikilink](https://github.com/tmr232/mdformat-wikilink)
### Pre-Commit
```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
Raw data
{
"_id": null,
"home_page": null,
"name": "mdformat_mkdocs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9.0",
"maintainer_email": null,
"keywords": "markdown, markdown-it, mdformat, mdformat_plugin_template",
"author": null,
"author_email": "kyleking <dev.act.kyle@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/32/e63095a2e99a771ed20b4cf9f282605add41a6fca672cdc5e3c39f316c74/mdformat_mkdocs-4.1.1.tar.gz",
"platform": null,
"description": "# mdformat-mkdocs\n\n[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]\n\n<!-- [![codecov.io][cov-badge]][cov-link]\n[cov-badge]: https://codecov.io/gh/executablebooks/mdformat-mkdocs/branch/main/graph/badge.svg\n[cov-link]: https://codecov.io/gh/executablebooks/mdformat-mkdocs\n -->\n\nAn [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))\n\nSupports:\n\n- Indents are converted to four-spaces instead of two\n - *Note*: when specifying `--align-semantic-breaks-in-lists`, the nested indent for ordered lists is three, but is otherwise a multiple of four\n- Unordered list bullets are converted to dashes (`-`) instead of `*`\n- 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)\n- [MkDocs-Material Admonitions\\*](https://squidfunk.github.io/mkdocs-material/reference/admonitions)\n - \\*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))\n- [MkDocs-Material Content Tabs\\*](https://squidfunk.github.io/mkdocs-material/reference/content-tabs)\n - \\*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.\n- [mkdocstrings Anchors (autorefs)](https://mkdocstrings.github.io/autorefs/#markdown-anchors)\n- [mkdocstrings Cross-References](https://mkdocstrings.github.io/usage/#cross-references)\n- [Python Markdown \"Abbreviations\"\\*](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations)\n - \\*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\n- [Python Markdown \"Snippets\"\\*](https://facelessuser.github.io/pymdown-extensions/extensions/snippets)\n - \\*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\n\nSee 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)\n\n## `mdformat` Usage\n\nAdd 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)\n\n**Tip**: this package specifies an \"extra\" (`'recommended'`) for plugins that work well with typical documentation managed by `mkdocs`:\n\n- [mdformat-beautysh](https://pypi.org/project/mdformat-beautysh)\n- [mdformat-black](https://pypi.org/project/mdformat-black)\n- [mdformat-config](https://pypi.org/project/mdformat-config)\n- [mdformat-footnote](https://pypi.org/project/mdformat-footnote)\n- [mdformat-frontmatter](https://pypi.org/project/mdformat-frontmatter)\n- [mdformat-simple-breaks](https://pypi.org/project/mdformat-simple-breaks)\n- [mdformat-tables](https://pypi.org/project/mdformat-tables)\n- [mdformat-web](https://pypi.org/project/mdformat-web)\n- [mdformat-wikilink](https://github.com/tmr232/mdformat-wikilink)\n\n### Pre-Commit\n\n```yaml\nrepos:\n - repo: https://github.com/executablebooks/mdformat\n rev: 0.7.19\n hooks:\n - id: mdformat\n additional_dependencies:\n - mdformat-mkdocs\n # Or\n # - \"mdformat-mkdocs[recommended]\"\n```\n\n### pipx/uv\n\n```sh\npipx install mdformat\npipx inject mdformat mdformat-mkdocs\n```\n\nOr with uv:\n\n```sh\nuv tool run --from mdformat-mkdocs mdformat\n```\n\n## HTML Rendering\n\nTo 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>\n\n```py\nfrom markdown_it import MarkdownIt\n\nfrom mdformat_mkdocs.mdit_plugins import (\n material_admon_plugin,\n material_content_tabs_plugin,\n mkdocstrings_autorefs_plugin,\n mkdocstrings_crossreference_plugin,\n pymd_abbreviations_plugin,\n)\n\nmd = MarkdownIt()\nmd.use(material_admon_plugin)\nmd.use(material_content_tabs_plugin)\nmd.use(mkdocstrings_autorefs_plugin)\nmd.use(mkdocstrings_crossreference_plugin)\nmd.use(pymd_abbreviations_plugin)\n\ntext = \"- Line 1\\n - `bash command`\\n - Line 3\"\nmd.render(text)\n# <ul>\n# <li>Line 1\n# <ul>\n# <li><code>bash command</code></li>\n# <li>Line 3</li>\n# </ul>\n# </li>\n# </ul>\n```\n\n## Configuration\n\n`mdformat-mkdocs` adds the CLI arguments:\n\n- `--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.\n\n ```txt\n # with: mdformat\n 1. Semantic line feed where the following line is\n three spaces deep\n\n # vs. \"mdformat --align-semantic-breaks-in-lists\"\n 1. Semantic line feed where the following line is\n three spaces deep\n ```\n\n- `--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\n\nYou can also use the toml configuration (https://mdformat.readthedocs.io/en/stable/users/configuration_file.html):\n\n```toml\n# .mdformat.toml\n\n[plugin.mkdocs]\nalign_semantic_breaks_in_lists = true\nignore_missing_references = true\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/kyleking/mdformat-mkdocs/blob/main/CONTRIBUTING.md)\n\n[ci-badge]: https://github.com/kyleking/mdformat-mkdocs/workflows/CI/badge.svg?branch=main\n[ci-link]: https://github.com/kyleking/mdformat-mkdocs/actions?query=workflow%3ACI+branch%3Amain+event%3Apush\n[pypi-badge]: https://img.shields.io/pypi/v/mdformat-mkdocs.svg\n[pypi-link]: https://pypi.org/project/mdformat-mkdocs\n",
"bugtrack_url": null,
"license": null,
"summary": "An mdformat plugin for `mkdocs`.",
"version": "4.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/kyleking/mdformat-mkdocs/issues",
"Changelog": "https://github.com/kyleking/mdformat-mkdocs/releases",
"homepage": "https://github.com/kyleking/mdformat-mkdocs"
},
"split_keywords": [
"markdown",
" markdown-it",
" mdformat",
" mdformat_plugin_template"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b6c48faf2063488af5a8978d4d6c4b09718006c88ec5c21f193121ad84017e25",
"md5": "a8a20764e2d9f0022e4e797f52ec4d91",
"sha256": "00defc794f8adb07bd792a7f260df91a1d3a125718b3bea5e312f386a19ad94a"
},
"downloads": -1,
"filename": "mdformat_mkdocs-4.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8a20764e2d9f0022e4e797f52ec4d91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0",
"size": 28393,
"upload_time": "2024-12-18T02:42:54",
"upload_time_iso_8601": "2024-12-18T02:42:54.666616Z",
"url": "https://files.pythonhosted.org/packages/b6/c4/8faf2063488af5a8978d4d6c4b09718006c88ec5c21f193121ad84017e25/mdformat_mkdocs-4.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd32e63095a2e99a771ed20b4cf9f282605add41a6fca672cdc5e3c39f316c74",
"md5": "033015103950aaab894c1550f463a2d4",
"sha256": "f58a06b45c3d22116425c28d6b4a72464223ca02abea2e009e1763ae9130cb2f"
},
"downloads": -1,
"filename": "mdformat_mkdocs-4.1.1.tar.gz",
"has_sig": false,
"md5_digest": "033015103950aaab894c1550f463a2d4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0",
"size": 26433,
"upload_time": "2024-12-18T02:42:56",
"upload_time_iso_8601": "2024-12-18T02:42:56.535834Z",
"url": "https://files.pythonhosted.org/packages/dd/32/e63095a2e99a771ed20b4cf9f282605add41a6fca672cdc5e3c39f316c74/mdformat_mkdocs-4.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 02:42:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kyleking",
"github_project": "mdformat-mkdocs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mdformat_mkdocs"
}
JSON
