mdsf-cli

# mdsf Format, and lint, markdown code snippets using your favorite tools. <a href="https://crates.io/crates/mdsf"><img src="https://img.shields.io/crates/v/mdsf.svg"></a> <a href="https://github.com/hougesen/mdsf/actions/workflows/validate.yml"><img src="https://github.com/hougesen/mdsf/actions/workflows/validate.yml/badge.svg"></a>  ## Table of contents  - [mdsf](#mdsf) - [Table of contents](#table-of-contents) - [Installation](#installation) - [Linux & MacOS](#linux--macos) - [Windows](#windows) - [Cargo](#cargo) - [npm/npx](#npmnpx) - [Homebrew](#homebrew) - [Conda](#conda) - [Usage](#usage) - [Formatting code](#formatting-code) - [Caching formatting results](#caching-formatting-results) - [Removing old caches](#removing-old-caches) - [Verifying code](#verifying-code) - [GitHub Action](#github-action) - [Visual Studio Code](#visual-studio-code) - [Vim / NeoVim](#vim--neovim) - [conform.nvim](#conformnvim) - [treefmt](#treefmt) - [Configuration](#configuration) - [Tools](#tools) - [Commands](#commands) - [Shell completions](#shell-completions) - [Bash](#bash) - [Bash](#bash-1) - [Fish](#fish) - [PowerShell](#powershell) - [Elvish](#elvish) - [Nushell](#nushell) - [Acknowledgement](#acknowledgement) - [Alternatives to mdsf](#alternatives-to-mdsf)  ## Installation The latest version of `mdsf` can be downloaded directly from [github.com/hougesen/mdsf/releases](https://github.com/hougesen/mdsf/releases). ### Linux & MacOS ```shell curl --proto '=https' --tlsv1.2 -LsSf https://github.com/hougesen/mdsf/releases/latest/download/mdsf-installer.sh | sh ``` ### Windows ```powershell powershell -ExecutionPolicy ByPass -c "irm https://github.com/hougesen/mdsf/releases/latest/download/mdsf-installer.ps1 | iex" ``` ### Cargo Install using the [published crate](https://crates.io/crates/mdsf): ```shell cargo install mdsf --locked ``` or directly from source: ```shell git clone git@github.com:hougesen/mdsf.git cargo install --path ./mdsf --bin mdsf ``` If you do not have Cargo installed, you need to [install it first](https://www.rust-lang.org/learn/get-started). ### npm/npx You can install `mdsf` using [npm](https://www.npmjs.com/package/mdsf-cli): ```shell npm install -g mdsf-cli mdsf format . ``` or run it directly using npx: ```shell npx mdsf-cli format . ``` ### Homebrew ```shell brew install hougesen/tap/mdsf ``` ### Conda An _unofficial_ (and unsupported) Conda package can be found at [https://anaconda.org/conda-forge/mdsf](https://anaconda.org/conda-forge/mdsf). ```shell conda install conda-forge::mdsf ``` ## Usage  ``` mdsf 0.8.5 Format, and lint, markdown code snippets using your favorite tools Mads Hougesen <mads@mhouge.dk> Usage: mdsf <COMMAND> Commands: format Run formatters on input files verify Verify files are formatted init Create a new mdsf config completions Generate shell completion cache-prune Remove caches help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print version ```  ### Formatting code The `format` command, as the name implies, is used to format documents. ```shell mdsf format file.md ```  ``` Run formatters on input files Usage: mdsf format [OPTIONS] [INPUT]... Arguments: [INPUT]... Path to files and/or directories Options: --stdin Read input from stdin and write output to stdout --config <CONFIG> Path to config --debug Log stdout and stderr of formatters --log-level <LOG_LEVEL> [possible values: trace, debug, info, warn, error, off] --threads <THREADS> Amount of threads to use. Defaults to 0 (auto). --cache Cache results --timeout <TIMEOUT> Tool timeout in seconds Defaults to no timeout -h, --help Print help (see a summary with '-h') -V, --version Print version ```  #### Caching formatting results To speed formatting caching can be enabled by supplying the `format` command with the `--cache` argument. ```shell mdsf format --cache docs/ ``` ##### Removing old caches Old caches can be removed by running the `mdsf cache-prune` command.  ``` Remove caches Usage: mdsf cache-prune Options: -h, --help Print help -V, --version Print version ```  ### Verifying code You can verify that the document is formatted using the `mdsf verify` command. ```shell mdsf verify docs/ ```  ``` Verify files are formatted Usage: mdsf verify [OPTIONS] [INPUT]... Arguments: [INPUT]... Path to files and/or directories Options: --stdin Read input from stdin and write output to stdout --config <CONFIG> Path to config --debug Log stdout and stderr of formatters --log-level <LOG_LEVEL> [possible values: trace, debug, info, warn, error, off] --threads <THREADS> Amount of threads to use. Defaults to 0 (auto). --timeout <TIMEOUT> Tool timeout in seconds Defaults to no timeout -h, --help Print help (see a summary with '-h') -V, --version Print version ```  ### GitHub Action There are a lot of different ways to run `mdsf` using GitHub actions. The easiest way, in my opinion, is to use the official GitHub action to install mdsf. After that you can run the binary like you would in your terminal. > \[!NOTE\] > mdsf is not a package manager. > > You must also install the tools you wish to use in your GitHub action. ```yaml name: mdsf on: push jobs: format: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Install mdsf uses: hougesen/mdsf@v0.8.5 - name: Run mdsf run: mdsf format --log-level warn . - name: Commit changes uses: EndBug/add-and-commit@v9 with: message: "style: formatted markdown code blocks" ``` ### Visual Studio Code [![](https://img.shields.io/visual-studio-marketplace/v/hougesen.mdsf?color=374151&label=Visual%20Studio%20Marketplace&labelColor=000&logo=visual-studio-code&logoColor=0098FF)](https://marketplace.visualstudio.com/items?itemName=hougesen.mdsf) [![](https://img.shields.io/visual-studio-marketplace/v/hougesen.mdsf?color=374151&label=Open%20VSX%20Registry&labelColor=000&logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHN2ZyB2aWV3Qm94PSI0LjYgNSA5Ni4yIDEyMi43IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoIGQ9Ik0zMCA0NC4yTDUyLjYgNUg3LjN6TTQuNiA4OC41aDQ1LjNMMjcuMiA0OS40em01MSAwbDIyLjYgMzkuMiAyMi42LTM5LjJ6IiBmaWxsPSIjYzE2MGVmIi8+CiAgPHBhdGggZD0iTTUyLjYgNUwzMCA0NC4yaDQ1LjJ6TTI3LjIgNDkuNGwyMi43IDM5LjEgMjIuNi0zOS4xem01MSAwTDU1LjYgODguNWg0NS4yeiIgZmlsbD0iI2E2MGVlNSIvPgo8L3N2Zz4=&logoColor=0098FF)](https://open-vsx.org/extension/hougesen/mdsf) mdsf can be run using the VSCode extension. > \[!NOTE\] > The mdsf VS Code extension does currently not support installing mdsf. > Which means mdsf must be installed using other means. ### Vim / NeoVim #### conform.nvim [conform.nvim](https://github.com/stevearc/conform.nvim) has native support for running mdsf. ```lua local conform = require("conform") conform.setup({ formatters_by_ft = { markdown = { "mdsf" }, -- ... }, -- ... }) ``` ### treefmt Add the following to your `treefmt.toml` to run mdsf using [treefmt](https://github.com/numtide/treefmt). ```toml # treefmt.toml [formatter.mdsf] command = "mdsf" options = ["format"] includes = ["*.md"] ``` ## Configuration The default configuration of `mdsf` aims to as simple as possible. For that reason the default formatter for each language is the one most people have installed. If you are interested in customizing which formatter is run, you can create a new `mdsf` configuration file by running `mdsf init`.  ``` Create a new mdsf config Usage: mdsf init Options: -h, --help Print help -V, --version Print version ```  `mdsf` supports running multiple formatters on the save code snippet. ```json { "languages": { // Only run `ruff` on Python snippets, "python": "ruff:format", // Run `usort` on file and then `black` "python": ["usort", "black"], // Run `usort`, if that fails run `isort`, finally run `black` "python": [["usort", "isort"], "black"], // Formatters listed under "*" will be run on any snippet. "*": ["typos"], // Formatters listed under "_" will only be run when there is not formatter configured for the file type OR globally ("*"). "_": "prettier" } } ``` ### Tools > \[!NOTE\] > mdsf is not a package manager. > > Only tools that are already installed will be used.  `mdsf` currently supports 296 tools. Feel free to open an issue/pull-request if your favorite tool/command is missing! 😃 | Name | Description | Categories | Languages | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [actionlint](https://github.com/rhysd/actionlint) | Static checker for GitHub Actions workflow files | `linter` | `yaml` | | [air](https://github.com/posit-dev/air) | R formatter and language server | `formatter` | `r` | | [alejandra](https://github.com/kamadorueda/alejandra) | The Uncompromising Nix Code Formatter | `formatter` | `nix` | | [alex](https://github.com/get-alex/alex) | Catch insensitive, inconsiderate writing | `spell-check` | `markdown` | | [ameba](https://github.com/crystal-ameba/ameba) | A static code analysis tool for Crystal | `linter` | `crystal` | | [ansible-lint](https://github.com/ansible/ansible-lint) | ansible-lint checks playbooks for practices and behavior that could potentially be improved and can fix some of the most common ones for you | `linter` | `ansible` | | [asmfmt](https://github.com/klauspost/asmfmt) | Go Assembler Formatter | `formatter` | `go` | | [astyle](https://gitlab.com/saalen/astyle) | A Free, Fast, and Small Automatic Formatter for C, C++, C++/CLI, Objective-C, C#, and Java Source Code | `formatter` | `c#`, `c++`, `c`, `java`, `objective-c` | | [auto-optional](https://github.com/luttik/auto-optional) | Adds the Optional type-hint to arguments where the default value is None | `formatter` | `python` | | [autocorrect](https://github.com/huacnlee/autocorrect) | A linter and formatter to help you to improve copywriting, correct spaces, words, and punctuations between CJK (Chinese, Japanese, Korean) | `spell-check` | | | [autoflake](https://github.com/pycqa/autoflake) | Removes unused imports and unused variables as reported by pyflakes | `linter` | `python` | | [autopep8](https://github.com/hhatto/autopep8) | A tool that automatically formats Python code to conform to the PEP 8 style guid | `formatter` | `python` | | [bashate](https://github.com/openstack/bashate) | Code style enforcement for bash programs | `formatter` | `bash` | | [beancount-black](https://github.com/launchplatform/beancount-black) | Opinionated code formatter, just like Python's black code formatter but for Beancount | `formatter` | `beancount` | | [beautysh](https://github.com/lovesegfault/beautysh) | A Bash beautifier for the masses | `formatter` | `bash`, `shell` | | [bibtex-tidy](https://github.com/flamingtempura/bibtex-tidy) | Cleaner and Formatter for BibTeX files | `formatter` | `bibtex` | | [bicep](https://github.com/azure/bicep) | Bicep is a declarative language for describing and deploying Azure resources | `formatter` | `bicep` | | [biome](https://github.com/biomejs/biome) | One toolchain for your web project | `formatter`, `linter` | `javascript`, `json`, `typescript`, `vue` | | [black](https://github.com/psf/black) | The uncompromising Python code formatter | `formatter` | `python` | | [blade-formatter](https://github.com/shufo/blade-formatter) | An opinionated blade template formatter for Laravel that respects readability | `formatter` | `blade`, `laravel`, `php` | | [blue](https://github.com/grantjenks/blue) | The slightly less uncompromising Python code formatter | `formatter` | `python` | | [bpfmt](https://source.android.com/docs/setup/reference/androidbp#formatter) | A formatter for Blueprint files | `formatter` | `blueprint` | | [brittany](https://github.com/lspitzner/brittany) | A Haskell source code formatter | `formatter` | `haskell` | | [brunette](https://github.com/odwyersoftware/brunette) | A best practice Python code formatter | `formatter` | `python` | | [bsfmt](https://github.com/rokucommunity/brighterscript-formatter) | A code formatter for BrightScript and BrighterScript | `formatter` | `brighterscript`, `brightscript` | | [bslint](https://github.com/rokucommunity/bslint) | A linter for BrightScript and BrighterScript | `linter` | `brightscript`, `brightscripter` | | [buf](https://buf.build/docs/reference/cli/buf/) | The best way of working with Protocol Buffers | `formatter` | `protobuf` | | [buildifier](https://github.com/bazelbuild/buildtools) | A bazel BUILD file formatter and | `formatter` | `bazel` | | [cabal-fmt](https://github.com/phadej/cabal-fmt) | An experiment of formatting .cabal files | `formatter` | `cabal` | | [cabal-prettify](https://github.com/kindaro/cabal-prettify) | Prettify your Cabal package configuration files | `formatter` | `cabal` | | [cabal](https://www.haskell.org/cabal/) | Cabal is a system for building and packaging Haskell libraries and programs | `formatter` | `cabal` | | [caddy](https://caddyserver.com/docs/command-line#caddy-fmt) | Formats or prettifies a Caddyfile | `formatter` | `caddy` | | [caramel](https://caramel.run/) | Formatter for the Caramel programming language | `formatter` | `caramel` | | [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) | CloudFormation Linter | `linter` | `cloudformation`, `json`, `yaml` | | [checkmake](https://github.com/mrtazz/checkmake) | Experimental linter/analyzer for Makefiles | `linter` | `makefile` | | [clang-format](https://clang.llvm.org/docs/ClangFormat.html) | A tool to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code | `formatter` | `c#`, `c++`, `c`, `java`, `javascript`, `json`, `objective-c`, `protobuf` | | [clang-tidy](https://clang.llvm.org/extra/clang-tidy/) | clang-tidy is a clang-based C++ “linter” tool | `linter` | `c++` | | [clj-kondo](https://github.com/clj-kondo/clj-kondo) | Static analyzer and linter for Clojure code that sparks joy | `linter` | `clojure`, `clojurescript` | | [cljfmt](https://github.com/weavejester/cljfmt) | A tool for formatting Clojure code | `formatter` | `clojure` | | [cljstyle](https://github.com/greglook/cljstyle) | A tool for formatting Clojure code | `formatter` | `clojure` | | [cmake-format](https://cmake-format.readthedocs.io/en/latest/cmake-format.html) | cmake-format can format your listfiles nicely so that they don't look like crap | `formatter` | `cmake` | | [cmake-lint](https://cmake-format.readthedocs.io/en/latest/lint-usage.html) | Lint CMake files | `linter` | `cmake` | | [codeql](https://docs.github.com/en/code-security/codeql-cli/codeql-cli-manual) | Format queries and libraries with CodeQL | `formatter` | `codeql` | | [codespell](https://github.com/codespell-project/codespell) | Check code for common misspellings | `spell-check` | | | [coffeelint](https://github.com/coffeelint/coffeelint) | Lint your CoffeeScript | `linter` | `coffeescript` | | [cppcheck](https://cppcheck.sourceforge.io/) | Cppcheck is a static analysis tool for C/C++ code | `linter` | `c++`, `c` | | [cpplint](https://github.com/cpplint/cpplint) | Static code checker for C++ | `linter` | `c++` | | [crlfmt](https://github.com/cockroachdb/crlfmt) | Formatter for CockroachDB's additions to the Go style guide | `formatter` | `go` | | [crystal](https://crystal-lang.org/) | Tools for the Crystal programming language | `formatter` | `crystal` | | [csharpier](https://csharpier.com/) | An Opinionated Code Formatter for C# | `formatter` | `c#` | | [css-beautify](https://github.com/beautifier/js-beautify) | A css formatter | `formatter` | `css` | | [csscomb](https://github.com/csscomb/csscomb.js) | CSS coding style formatter | `formatter` | `css` | | [csslint](https://github.com/csslint/csslint) | Automated linting of Cascading Stylesheets | `linter` | `css` | | [curlylint](https://github.com/thibaudcolas/curlylint) | Experimental HTML templates linting for Jinja, Nunjucks, Django templates, Twig, Liquid | `linter` | `django`, `html`, `jinja`, `liquid`, `nunjucks`, `twig` | | [d2](https://d2lang.com/) | A modern language that turns text to diagrams | `formatter` | `d2` | | [dart](https://dart.dev/tools) | Formatter and linter for Dart | `formatter`, `linter` | `dart`, `flutter` | | [dcm](https://dcm.dev/) | Code Quality Tool for Flutter Developers | `formatter`, `linter` | `dart`, `flutter` | | [deadnix](https://github.com/astro/deadnix) | Scan Nix files for dead code | `linter` | `nix` | | [deno](https://docs.deno.com/runtime/reference/cli/) | Formatter and linter for JavaScript and TypeScript | `formatter`, `linter` | `javascript`, `json`, `typescript` | | [dfmt](https://github.com/dlang-community/dfmt) | Dfmt is a formatter for D source code | `formatter` | `d` | | [dhall](https://dhall-lang.org/) | Format Dhall files | `formatter` | `dhall` | | [djade](https://github.com/adamchainz/djade) | A Django template formatter | `formatter` | `django`, `python` | | [djlint](https://www.djlint.com/) | Lint & Format HTML Templates | `formatter`, `linter` | `handlebars`, `html`, `jinja`, `mustache`, `nunjucks`, `twig` | | [docformatter](https://github.com/PyCQA/docformatter) | Formats docstrings to follow PEP 257 | `formatter` | `python` | | [dockfmt](https://github.com/jessfraz/dockfmt) | Dockerfile format and parser. Like `gofmt` but for Dockerfiles | `formatter` | `docker` | | [docstrfmt](https://github.com/LilSpazJoekp/docstrfmt) | A formatter for Sphinx flavored reStructuredText | `formatter` | `python`, `restructuredtext`, `sphinx` | | [doctoc](https://github.com/thlorenz/doctoc) | Generates table of contents for markdown files | `formatter` | `markdown` | | [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) | Lightning-fast linter for .env files | `linter` | `env` | | [dprint](https://dprint.dev/) | A pluggable and configurable code formatting platform written in Rust | `formatter` | | | [dscanner](https://github.com/dlang-community/d-scanner) | Swiss-army knife for D source code | `linter` | `d` | | [easy-coding-standard](https://github.com/easy-coding-standard/easy-coding-standard) | The Easiest way to add coding standard to your PHP project | `formatter`, `linter` | `php` | | [efmt](https://github.com/sile/efmt) | Erlang code formatter | `formatter` | `erlang` | | [elm-format](https://github.com/avh4/elm-format) | elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide | `formatter` | `elm` | | [eradicate](https://github.com/PyCQA/eradicate) | Removes commented-out code from Python files | `linter` | `python` | | [erb-formatter](https://github.com/nebulab/erb-formatter) | Format ERB files with speed and precision | `formatter` | `erb`, `ruby` | | [erlfmt](https://github.com/whatsapp/erlfmt) | An automated code formatter for Erlang | `formatter` | `erlang` | | [eslint](https://github.com/eslint/eslint/) | Find and fix problems in your JavaScript code | `linter` | `javascript`, `typescript` | | [fantomas](https://github.com/fsprojects/fantomas) | FSharp source code formatter | `formatter` | `fsharp` | | [fish_indent](https://fishshell.com/docs/current/cmds/fish_indent.html) | Fish indenter and prettifier | `formatter` | `fish` | | [fixjson](https://github.com/rhysd/fixjson) | JSON Fixer for Humans using (relaxed) JSON5 | `formatter`, `linter` | `json5`, `json` | | [floskell](https://github.com/ennocramer/floskell) | Floskell is a flexible Haskell source code pretty printer | `formatter` | `haskell` | | [flynt](https://github.com/ikamensh/flynt) | A tool to automatically convert old string literal formatting to f-strings | `formatter` | `python` | | [fnlfmt](https://git.sr.ht/~technomancy/fnlfmt) | A formatter for Fennel code | `formatter` | `fennel` | | [forge](https://github.com/foundry-rs/foundry) | A Solidity formatter | `formatter` | `solidity` | | [fortitude](https://github.com/plasmafair/fortitude) | A Fortran linter, written in Rust | `linter` | | | [fortran-linter](https://github.com/cphyc/fortran-linter) | A simple fortran syntax checker, including automatic fixing of the code | `formatter`, `linter` | `fortran` | | [fourmolu](https://github.com/fourmolu/fourmolu) | A formatter for Haskell source code | `formatter` | `haskell` | | [fprettify](https://github.com/fortran-lang/fprettify) | Auto-formatter for modern Fortran source code | `formatter` | `fortran` | | [futhark](https://futhark.readthedocs.io/en/latest/man/futhark-fmt.html) | Code formatter for the furhark programming language | `formatter` | `futhark` | | [gci](https://github.com/daixiang0/gci) | GCI, a tool that control golang package import order and make it always deterministic | `formatter` | `go` | | [gdformat](https://github.com/scony/godot-gdscript-toolkit) | GDScript formatter | `formatter` | `gdscript` | | [gdlint](https://github.com/scony/godot-gdscript-toolkit) | GDScript linter | `linter` | `gdscript` | | [gersemi](https://github.com/blankspruce/gersemi) | A formatter to make your CMake code the real treasure | `formatter` | `cmake` | | [gleam](https://gleam.run/) | Format Gleam source code | `formatter` | `gleam` | | [gluon](https://github.com/gluon-lang/gluon) | Code formatting for the gluon programming language | `formatter` | `gluon` | | [gofmt](https://pkg.go.dev/cmd/gofmt) | Gofmt formats Go programs | `formatter` | `go` | | [gofumpt](https://github.com/mvdan/gofumpt) | A stricter gofmt | `formatter` | `go` | | [goimports-reviser](https://github.com/incu6us/goimports-reviser) | Right imports sorting & code formatting tool (goimports alternative) | `formatter` | `go` | | [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) | goimports updates your Go import lines, adding missing ones and removing unreferenced ones | `formatter` | `go` | | [golangci-lint](https://github.com/golangci/golangci-lint) | Fast linters runner for Go | `formatter`, `linter` | `go` | | [golines](https://github.com/segmentio/golines) | A golang formatter that fixes long lines | `formatter` | `go` | | [google-java-format](https://github.com/google/google-java-format) | Reformats Java source code to comply with Google Java Style | `formatter` | `java`