Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files

Overview

Documentation Status Build Status codecov.io PyPI version

mdformat

CommonMark compliant Markdown formatter

Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files. Mdformat is a Unix-style command-line tool as well as a Python library.

Find out more in the docs.

Installing

Install with CommonMark support:

pip install mdformat

Alternatively install with GitHub Flavored Markdown (GFM) support:

pip install mdformat-gfm

Or with Markedly Structured Text (MyST) support:

pip install mdformat-myst

Command line usage

Format files

Format files README.md and CHANGELOG.md in place

mdformat README.md CHANGELOG.md

Format .md files in current working directory recursively

mdformat .

Read Markdown from standard input until EOF. Write formatted Markdown to standard output.

mdformat -

Check formatting

mdformat --check README.md CHANGELOG.md

This will not apply any changes to the files. If a file is not properly formatted, the exit code will be non-zero.

Options

[email protected]:~$ mdformat --help
usage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf}] [paths [paths ...]]

CommonMark compliant Markdown formatter

positional arguments:
  paths                 files to format

optional arguments:
  -h, --help            show this help message and exit
  --check               do not apply changes to files
  --version             show program's version number and exit
  --number              apply consecutive numbering to ordered lists
  --wrap {keep,no,INTEGER}
                        paragraph word wrap mode (default: keep)
  --end-of-line {lf,crlf}
                        output file line ending mode (default: lf)

Documentation

This README merely provides a quickstart guide for the command line interface. For more information refer to the documentation. Here's a few pointers to get you started:

Frequently Asked Questions

Why not use Prettier instead?

Mdformat is pure Python code! Python is pre-installed on macOS and virtually any Linux distribution, meaning that typically little to no additional installations are required to run mdformat. This argument also holds true when using together with pre-commit (also Python). Prettier on the other hand requires Node.js/npm.

Prettier suffers from numerous bugs, many of which cause changes in Markdown AST and rendered HTML. Many of these bugs are a consequence of using remark-parse v8.x as Markdown parser which, according to the author themselves, is inferior to markdown-it used by mdformat. remark-parse v9.x is advertised as CommonMark compliant and presumably would fix many of the issues, but is not used by Prettier (v2.3.1) yet.

Prettier (v2.3.1), being able to format many languages other than Markdown, is a large package with 65 direct dependencies (mdformat only has 2 in Python 3.8+). This can be a disadvantage in many environments, one example being size optimized Docker images.

Mdformat's parser extension plugin API allows not only customization of the Markdown specification in use, but also advanced features like automatic table of contents generation. Also provided is a code formatter plugin API enabling integration of embedded code formatting for any programming language.

What's wrong with the mdformat logo? It renders incorrectly and is just terrible in general.

Nope, the logo is actually pretty great – you're terrible. The logo is more a piece of art than a logo anyways, depicting the horrors of poorly formatted text documents. I made it myself!

That said, if you have any graphic design skills and want to contribute a revised version, a PR is more than welcome 😄 .

Owner
Executable Books
An open collaboration to create executable books with Jupyter
Executable Books
Provides syntax for Python-Markdown which allows for the inclusion of the contents of other Markdown documents.

Markdown-Include This is an extension to Python-Markdown which provides an "include" function, similar to that found in LaTeX (and also the C pre-proc

Chris MacMackin 85 Dec 30, 2022
A lightweight and fast-to-use Markdown document generator based on Python

A lightweight and fast-to-use Markdown document generator based on Python

快乐的老鼠宝宝 1 Jan 10, 2022
A Straightforward Markdown Journal

Introducing Pepys: A straightforward markdown journal "It is rightly made for those who love to document their daily life events" - FOSSBytes Pepys is

Luke Briggs 23 Nov 12, 2022
A command line tool that can convert Day One data into markdown files.

Introduction Features Before Start Export data from Day One Check Integrity Special Cases for Photo Extension Name Audio Extension Name Usage Known Is

gyro永不抽风 26 Dec 31, 2022
markdown2: A fast and complete implementation of Markdown in Python

Markdown is a light text markup format and a processor to convert that to HTML. The originator describes it as follows: Markdown is a text-to-HTML con

Trent Mick 2.4k Dec 30, 2022
A Python implementation of John Gruber’s Markdown with Extension support.

Python-Markdown This is a Python implementation of John Gruber's Markdown. It is almost completely compliant with the reference implementation, though

Python-Markdown 3.1k Dec 31, 2022
Converts a grading Excel sheet into Markdown documents.

GradeDocs Turns Excel worksheets into grade/score documents. Example Given such an Excel Worksheet (see examples/example.xlsx): The following commands

Patrick Bucher 1 Dec 19, 2021
Static site generator that supports Markdown and reST syntax. Powered by Python.

Pelican Pelican is a static site generator, written in Python. Write content in reStructuredText or Markdown using your editor of choice Includes a si

Pelican dev team 11.3k Jan 05, 2023
Markdown Presentations for Tech Conferences, Training, Developer Advocates, and Educators.

March 1, 2021: Service on gitpitch.com has been shutdown permanently. GitPitch 4.0 Docs Twitter About Watch the Introducing GitPitch 4.0 Video Visit t

David Russell 5.4k Jan 05, 2023
Preview GitHub README.md files locally before committing them.

Grip -- GitHub Readme Instant Preview Render local readme files before sending off to GitHub. Grip is a command-line server application written in Pyt

Joe Esposito 5.9k Jan 08, 2023
A super simple script which uses the GitHub API to convert your markdown files to GitHub styled HTML site.

A super simple script which uses the GitHub API to convert your markdown files to GitHub styled HTML site.

Çalgan Aygün 213 Dec 22, 2022
Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files

Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files. Mdformat is a Unix-style command-line tool as well as a Python library.

Executable Books 180 Jan 06, 2023
Livemark is a static page generator that extends Markdown with interactive charts, tables, and more.

Livermark This software is in the early stages and is not well-tested Livemark is a static site generator that extends Markdown with interactive chart

Frictionless Data 86 Dec 25, 2022
CiteURL is an extensible tool that parses legal citations and makes links to websites where you can read the cited language for free.

CiteURL is an extensible tool that parses legal citations and makes links to websites where you can read the cited language for free. It can be used t

15 Dec 27, 2022
A markdown extension for converting Leiden+ epigraphic text to TEI XML/HTML

LeidenMark $ pip install leidenmark A Python Markdown extension for converting Leiden+ epigraphic text to TEI XML/HTML. Inspired by the Brill plain te

André van Delft 2 Aug 04, 2021
Pure-python-server - A blogging platform written in pure python for developer to share their coding knowledge

Pure Python web server - PyProject A blogging platform written in pure python (n

Srikar Koushik Satya Viswanadha 10 Nov 07, 2022
Yuque2md - Offline download the markdown file and image from yuque

yuque2md 按照语雀知识库里的目录,导出语雀知识库中所有的markdown文档,并离线图片到本地 使用 安装 Python3.x clone 项目 下载依

JiaJianHuang 4 Oct 30, 2022
Comprehensive Markdown plugin built for Django

Django MarkdownX Django MarkdownX is a comprehensive Markdown plugin built for Django, the renowned high-level Python web framework, with flexibility,

neutronX 740 Jan 08, 2023
A markdown template manager for writing API docs in python.

DocsGen-py A markdown template manager for writing API docs in python. Contents Usage API Reference Usage You can install the latest commit of this re

Ethan Evans 1 May 10, 2022
A automated python script that creates mark-down files to read for the aes keys and other useful information.

Archive A automated python script that creates mark-down files to read for the aes keys and other useful information. Table of Contents Benbot Automat

Tector 13 Dec 14, 2022