{"id":22393472,"url":"https://github.com/hukkin/mdformat","last_synced_at":"2025-12-12T01:02:59.104Z","repository":{"id":37957967,"uuid":"278875517","full_name":"hukkin/mdformat","owner":"hukkin","description":"CommonMark compliant Markdown formatter","archived":false,"fork":false,"pushed_at":"2025-03-31T17:18:13.000Z","size":724,"stargazers_count":575,"open_issues_count":32,"forks_count":49,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-08T00:06:23.628Z","etag":null,"topics":["cli","codeformatter","commonmark","formatter","markdown","mdformat","pre-commit","python"],"latest_commit_sha":null,"homepage":"https://mdformat.rtfd.io","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/hukkin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2020-07-11T14:16:01.000Z","updated_at":"2025-05-07T12:36:05.000Z","dependencies_parsed_at":"2023-12-25T17:49:24.644Z","dependency_job_id":"30a84536-b4b1-4244-9a48-5e3e882666d3","html_url":"https://github.com/hukkin/mdformat","commit_stats":{"total_commits":327,"total_committers":11,"mean_commits":"29.727272727272727","dds":"0.27522935779816515","last_synced_commit":"0cbd2054dedf98ec8366001c8a16eacfa85cebc1"},"previous_names":["choldgraf/mdformat","hukkin/mdformat"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hukkin%2Fmdformat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hukkin","download_url":"https://codeload.github.com/hukkin/mdformat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254092659,"owners_count":22013290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","codeformatter","commonmark","formatter","markdown","mdformat","pre-commit","python"],"created_at":"2024-12-05T05:02:56.588Z","updated_at":"2025-12-12T01:02:54.071Z","avatar_url":"https://github.com/hukkin.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n[![Documentation Status](https://readthedocs.org/projects/mdformat/badge/?version=latest)](https://mdformat.readthedocs.io/en/latest/?badge=latest)\n[![Build Status](https://github.com/hukkin/mdformat/actions/workflows/tests.yaml/badge.svg?branch=master)](https://github.com/hukkin/mdformat/actions?query=workflow%3ATests+branch%3Amaster+event%3Apush)\n[![codecov.io](https://codecov.io/gh/hukkin/mdformat/branch/master/graph/badge.svg)](https://codecov.io/gh/hukkin/mdformat)\n[![PyPI version](https://img.shields.io/pypi/v/mdformat)](https://pypi.org/project/mdformat)\n\n# ![mdformat](https://raw.githubusercontent.com/hukkin/mdformat/master/docs/_static/logo.svg)\n\n\u003e CommonMark compliant Markdown formatter\n\n\u003c/div\u003e\n\n\u003c!-- start mini-description --\u003e\n\nMdformat is an opinionated Markdown formatter\nthat can be used to enforce a consistent style in Markdown files.\nMdformat is a Unix-style command-line tool as well as a Python library.\n\n\u003c!-- end mini-description --\u003e\n\nFind out more in the [docs](https://mdformat.readthedocs.io).\n\n\u003c!-- start installing --\u003e\n\n## Installing\n\nInstall with [CommonMark](https://spec.commonmark.org/current/) support:\n\n```bash\npipx install mdformat\n```\n\nInstall with [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/) support:\n\n```bash\npipx install mdformat\npipx inject mdformat mdformat-gfm\n```\n\nNote that GitHub's Markdown renderer supports syntax extensions not included in the GFM specification.\nFor full GitHub support do:\n\n```bash\npipx install mdformat\npipx inject mdformat mdformat-gfm mdformat-frontmatter mdformat-footnote mdformat-gfm-alerts\n```\n\nInstall with [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) support:\n\n```bash\npipx install mdformat\npipx inject mdformat mdformat-myst\n```\n\n\u003c!-- end installing --\u003e\n\n\u003c!-- start cli-usage --\u003e\n\n## Command line usage\n\n### Format files\n\nFormat files `README.md` and `CHANGELOG.md` in place\n\n```bash\nmdformat README.md CHANGELOG.md\n```\n\nFormat `.md` files in current working directory recursively\n\n```bash\nmdformat .\n```\n\nRead Markdown from standard input until `EOF`.\nWrite formatted Markdown to standard output.\n\n```bash\nmdformat -\n```\n\n### Check formatting\n\n```bash\nmdformat --check README.md CHANGELOG.md\n```\n\nThis will not apply any changes to the files.\nIf a file is not properly formatted, the exit code will be non-zero.\n\n### Options\n\n```console\nfoo@bar:~$ mdformat --help\nusage: mdformat [-h] [--check] [--no-validate] [--version] [--number]\n                [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}]\n                [--exclude PATTERN] [--extensions EXTENSION]\n                [--codeformatters LANGUAGE]\n                [paths ...]\n\nCommonMark compliant Markdown formatter\n\npositional arguments:\n  paths                 files to format\n\noptions:\n  -h, --help            show this help message and exit\n  --check               do not apply changes to files\n  --no-validate         do not validate that the rendered HTML is consistent\n  --version             show program's version number and exit\n  --number              apply consecutive numbering to ordered lists\n  --wrap {keep,no,INTEGER}\n                        paragraph word wrap mode (default: keep)\n  --end-of-line {lf,crlf,keep}\n                        output file line ending mode (default: lf)\n  --exclude PATTERN     exclude files that match the Unix-style glob pattern\n                        (multiple allowed)\n  --extensions EXTENSION\n                        require and enable an extension plugin (multiple\n                        allowed) (use `--no-extensions` to disable) (default:\n                        all enabled)\n  --codeformatters LANGUAGE\n                        require and enable a code formatter plugin (multiple\n                        allowed) (use `--no-codeformatters` to disable)\n                        (default: all enabled)\n```\n\nThe `--exclude` option is only available on Python 3.13+.\n\n\u003c!-- end cli-usage --\u003e\n\n## Documentation\n\nThis README merely provides a quickstart guide for the command line interface.\nFor more information refer to the [documentation](https://mdformat.readthedocs.io).\nHere's a few pointers to get you started:\n\n- [Style guide](https://mdformat.readthedocs.io/en/stable/users/style.html)\n- [Python API usage](https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#python-api-usage)\n- [Usage as a pre-commit hook](https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook)\n- [Plugin usage](https://mdformat.readthedocs.io/en/stable/users/plugins.html)\n- [Plugin development guide](https://mdformat.readthedocs.io/en/stable/contributors/contributing.html)\n- [List of code block formatter plugins](https://mdformat.readthedocs.io/en/stable/users/plugins.html#existing-plugins)\n- [List of parser extension plugins](https://mdformat.readthedocs.io/en/stable/users/plugins.html#id1)\n- [Changelog](https://mdformat.readthedocs.io/en/stable/users/changelog.html)\n\n\u003c!-- start faq --\u003e\n\n## Frequently Asked Questions\n\n### Why does mdformat backslash escape special syntax specific to MkDocs / Hugo / Obsidian / GitHub / some other Markdown engine?\n\nMdformat is a CommonMark formatter.\nIt doesn't have out-of-the-box support for syntax other than what is defined in [the CommonMark specification](https://spec.commonmark.org/current/).\n\nThe custom syntax that these Markdown engines introduce typically redefines the meaning of\nangle brackets, square brackets, parentheses, hash character — characters that are special in CommonMark.\nMdformat often resorts to backslash escaping these characters to ensure its formatting changes never alter a rendered document.\n\nAdditionally some engines, namely MkDocs,\n[do not support](https://github.com/mkdocs/mkdocs/issues/1835) CommonMark to begin with,\nso incompatibilities are unavoidable.\n\nLuckily mdformat is extensible by plugins.\nFor many Markdown engines you'll find support by searching\n[the plugin docs](https://mdformat.readthedocs.io/en/stable/users/plugins.html)\nor [mdformat GitHub topic](https://github.com/topics/mdformat).\n\nYou may also want to consider a documentation generator that adheres to CommonMark as its base syntax\ne.g. [mdBook](https://rust-lang.github.io/mdBook/)\nor [Sphinx with Markdown](https://www.sphinx-doc.org/en/master/usage/markdown.html).\n\n### Why not use [Prettier](https://github.com/prettier/prettier) instead?\n\nMdformat is pure Python code!\nPython is pre-installed on macOS and virtually any Linux distribution,\nmeaning that typically little to no additional installations are required to run mdformat.\nThis argument also holds true when using together with\n[pre-commit](https://github.com/pre-commit/pre-commit) (also Python).\nPrettier on the other hand requires Node.js/npm.\n\nPrettier suffers from\n[numerous](https://github.com/prettier/prettier/issues?q=is%3Aopen+label%3Alang%3Amarkdown+label%3Atype%3Abug+)\nbugs,\nmany of which cause changes in Markdown AST and rendered HTML.\nMany of these bugs are a consequence of using\n[`remark-parse`](https://github.com/remarkjs/remark/tree/main/packages/remark-parse)\nv8.x as Markdown parser which,\naccording to the author themselves,\nis [inferior to markdown-it](https://github.com/remarkjs/remark/issues/75#issuecomment-143532326) used by mdformat.\n`remark-parse` v9.x is advertised as CommonMark compliant\nand presumably would fix many of the issues,\nbut is not used by Prettier (v3.3.3) yet.\n\nPrettier (v3.3.3), being able to format many languages other than Markdown,\nis a large package with 73 direct dependencies\n(mdformat only has one in Python 3.11+).\nThis can be a disadvantage in many environments,\none example being size optimized Docker images.\n\nMdformat's parser extension plugin API allows not only customization of the Markdown specification in use,\nbut also advanced features like [automatic table of contents generation](https://github.com/hukkin/mdformat-toc).\nAlso provided is a code formatter plugin API enabling integration of embedded code formatting for any programming language.\n\n### What's wrong with the mdformat logo? It renders incorrectly and is just terrible in general.\n\nNope, the logo is actually pretty great – you're terrible.\nThe logo is more a piece of art than a logo anyways,\ndepicting the horrors of poorly formatted text documents.\nI made it myself!\n\nThat said, if you have any graphic design skills and want to contribute a revised version, a PR is more than welcome 😄.\n\n\u003c!-- end faq --\u003e\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhukkin%2Fmdformat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhukkin%2Fmdformat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhukkin%2Fmdformat/lists"}