💡 A Markdown formatter that follow the CommonMark. Like gofmt, but for Markdown.
Recently, I have frequently used Markdown to write documents, and it is difficult to manage the format when there are too many contents. I often see lumps of markdown contents crowded together, it caused my eyebrows to be crowded together.
Fortunately, the powerful structured Markdown engine lute, its support for Chinese context is also very good, so I developed this Markdown formatting command line tool mdfmt with the lute engine, welcome everyone to try 👏🏻
- Support multiple inputs: standard input, file, directory and wildcard. The specified directory will recursively format all markdown files under the directory
- Support Rewriting: write the results to (source) files instead of standard output
- Support display difference: display the difference before and after markdown formatting, Instead of rewriting files
- Support listing formatted files
- Cross platform: Linux, windows, Mac
- One-click installation: support one-click installation
mdfmtthroughHomebrew,go install, etc.
To get the binary just download the latest release for your OS/Arch from the release page and put the binary somewhere convenient.
The elliotxx/tap has macOS and GNU/Linux pre-built binaries available:
brew install elliotxx/tap/mdfmt
Starting with Go 1.17, you can install mdfmt from source using go install:
go install github.com/elliotxx/mdfmt/cmd/mdfmt@latest
NOTE: This will install mdfmt based on the latest available code base. Even though the goal is that the latest commit on the main branch should always be a stable and usable version, this is not the recommended way to install and use mdfmt. The version output will show mdfmt version (default-version) for go install based builds.
Docker users can use the following commands to pull the latest image of the mdfmt:
docker pull elliotxx/mdfmt
Verification:
$ docker run --rm elliotxx/mdfmt:latest mdfmt -h
...
$ docker run --rm elliotxx/mdfmt:latest mdfmt -V
...
$ docker run -v $PWD:$PWD --rm elliotxx/mdfmt:latest mdfmt -d /Users/yym/workspace/mdfmt/pkg/md/testdata/hello-more.md
diff -u /Users/yym/workspace/mdfmt/pkg/md/testdata/hello-more.md.orig /Users/yym/workspace/mdfmt/pkg/md/testdata/hello-more.md
--- /Users/yym/workspace/mdfmt/pkg/md/testdata/hello-more.md.orig
+++ /Users/yym/workspace/mdfmt/pkg/md/testdata/hello-more.md
@@ -1,6 +1,7 @@
# hello
+
> hello
-|name|age|
-|--|--|
-|Mike|18|
+| name | age |
+| ---- | --- |
+| Mike | 18 |$ mdfmt -h
A Markdown formatter that follow the CommonMark. Like gofmt, but for Markdown.
Usage:
mdfmt [flags] [path ...]
Examples:
# Format specified Markdown file, and write to stdout
mdfmt README.md
# Format and rewrite for specified Markdown file
mdfmt -w README.md
# Display diffs instead of rewriting Markdown files
mdfmt -d README.md
# List files whose formatting differs from mdfmt's
mdfmt -l .
# Format, rewrite, and display diffs for specified Markdown file
mdfmt -d -w README.md
# Format and rewrite all Markdown file in current directory
mdfmt -w *.md
# Recursive format and rewrite all Markdown file in current directory
mdfmt -w .
# Format and rewrite the specified Markdown file and directory
mdfmt -w README.md testdir/
# Format stdin to stdout
cat README.md | mdfmt
# Show version info
mdfmt -V
Flags:
-d, --diff display diffs instead of rewriting files
-h, --help help for mdfmt
-l, --list list files whose formatting differs from mdfmt's
-V, --version show version info
-w, --write write result to (source) file instead of stdout
- The Markdown engine uses lute, cool!
- The CLI Template uses elliotxx/go-cli-prototype
- The specification follows GFM/CommonMark
- Pretty git commit message using gitmoji-cli