{"id":16729065,"url":"https://github.com/kyleking/mdformat-mkdocs","last_synced_at":"2026-01-26T14:02:49.190Z","repository":{"id":65003450,"uuid":"579791674","full_name":"KyleKing/mdformat-mkdocs","owner":"KyleKing","description":"An mdformat plugin for mkdocs and Material for MkDocs","archived":false,"fork":false,"pushed_at":"2026-01-24T23:35:18.000Z","size":586,"stargazers_count":30,"open_issues_count":3,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-25T12:35:46.614Z","etag":null,"topics":["mdformat"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KyleKing.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2022-12-18T23:23:20.000Z","updated_at":"2026-01-16T05:19:56.000Z","dependencies_parsed_at":"2023-12-26T23:27:05.666Z","dependency_job_id":"c8852f9b-961f-4659-b4c0-59383ecb01f3","html_url":"https://github.com/KyleKing/mdformat-mkdocs","commit_stats":{"total_commits":14,"total_committers":1,"mean_commits":14.0,"dds":0.0,"last_synced_commit":"b50e475a5a16e99958503bf8637d001f47626418"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":"executablebooks/mdformat-plugin","purl":"pkg:github/KyleKing/mdformat-mkdocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyleKing%2Fmdformat-mkdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyleKing%2Fmdformat-mkdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyleKing%2Fmdformat-mkdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyleKing%2Fmdformat-mkdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KyleKing","download_url":"https://codeload.github.com/KyleKing/mdformat-mkdocs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KyleKing%2Fmdformat-mkdocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28780037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mdformat"],"created_at":"2024-10-12T23:13:11.501Z","updated_at":"2026-01-26T14:02:49.184Z","avatar_url":"https://github.com/KyleKing.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdformat-mkdocs\n\n[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]\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- [MkDocs-Material Definition Lists](https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists)\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 \"Attribute Lists\"](https://python-markdown.github.io/extensions/attr_list)\n    - Preserves attribute list syntax when using `--wrap` mode\n- [PyMdown Extensions \"Arithmatex\" (Math/LaTeX Support)](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex) ([Material for MkDocs Math](https://squidfunk.github.io/mkdocs-material/reference/math))\n    - This plugin combines three math rendering plugins from mdit-py-plugins:\n        1. **dollarmath**: Handles `$...$` (inline) and `$$...$$` (block) with smart dollar mode that prevents false positives (e.g., `$3.00` is not treated as math)\n        1. **texmath**: Handles `\\(...\\)` (inline) and `\\[...\\]` (block) LaTeX bracket notation\n        1. **amsmath**: Handles LaTeX environments like `\\begin{align}...\\end{align}`, `\\begin{cases}...\\end{cases}`, `\\begin{matrix}...\\end{matrix}`, etc.\n    - Can be deactivated entirely with the `--no-mkdocs-math` flag\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### Optional Extras\n\nThis package specifies two optional \"extra\" plugins (`'recommended'` and `'recommended-mdsf'` ) for plugins that work well with typical documentation managed by `mkdocs`:\n\n- For `'recommended'`:\n    - [mdformat-beautysh](https://pypi.org/project/mdformat-beautysh)\n    - [mdformat-config](https://pypi.org/project/mdformat-config)\n    - [mdformat-footnote](https://pypi.org/project/mdformat-footnote)\n    - [mdformat-front-matters](https://pypi.org/project/mdformat-front-matters) (previously [mdformat-frontmatter](https://pypi.org/project/mdformat-frontmatter))\n    - [mdformat-gfm](https://github.com/hukkin/mdformat-gfm)\n    - [mdformat-ruff](https://github.com/Freed-Wu/mdformat-ruff)\n    - [mdformat-simple-breaks](https://pypi.org/project/mdformat-simple-breaks)\n    - [mdformat-web](https://pypi.org/project/mdformat-web)\n    - [mdformat-wikilink](https://github.com/tmr232/mdformat-wikilink)\n- For `'recommended-mdsf'`:\n    - Instead of `mdformat-beautysh`, `mdformat-config`, `mdformat-ruff`, and `mdformat-web`, the \"mdsf\" extras install `mdformat-hooks`, which allows the use of `mdsf` for formatting code blocks in hundreds of languages using CLI formatters you already have installed; however, this requires extra configuration, so make sure to see the README: \u003chttps://github.com/KyleKing/mdformat-hooks\u003e\n\n### pre-commit/prek\n\n```yaml\nrepos:\n  - repo: https://github.com/executablebooks/mdformat\n    rev: 1.0.0\n    hooks:\n      - id: mdformat\n        additional_dependencies:\n          - mdformat-mkdocs\n          # Or\n          # - \"mdformat-mkdocs[recommended-mdsf]\u003e=5.1.0\"\n          # Or\n          # - \"mdformat-mkdocs[recommended]\"\n```\n\n### uvx\n\n```sh\nuvx --with=mdformat-mkdocs mdformat\n```\n\nOr with pipx:\n\n```sh\npipx install mdformat\npipx inject mdformat mdformat-mkdocs\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: \u003chttps://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser\u003e\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# \u003cul\u003e\n# \u003cli\u003eLine 1\n# \u003cul\u003e\n# \u003cli\u003e\u003ccode\u003ebash command\u003c/code\u003e\u003c/li\u003e\n# \u003cli\u003eLine 3\u003c/li\u003e\n# \u003c/ul\u003e\n# \u003c/li\u003e\n# \u003c/ul\u003e\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\n- `--no-mkdocs-math` if set, deactivate math/LaTeX rendering (Arithmatex). By default, math is enabled. This can be useful if you want to format markdown without processing math syntax.\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\nno_mkdocs_math = 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/actions/workflows/tests.yml/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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyleking%2Fmdformat-mkdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkyleking%2Fmdformat-mkdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkyleking%2Fmdformat-mkdocs/lists"}