Awesome

mdsf

Format markdown code snippets using your favorite code formatters.

<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
  • Table of contents
  • Installation
    • Linux & MacOS
    • Windows
    • Cargo
    • npm/npx
    • Homebrew
  • Usage
    • Formatting code
    • Verifying code
  • Configuration
    • Tools
    • Commands
  • Shell completions
    • Bash
    • Bash
    • Fish
    • PowerShell
    • Elvish
  • Acknowledgement
  • Alternatives to mdsf

Installation

The latest version of mdsf can be downloaded directly from github.com/hougesen/mdsf/releases.

Linux & MacOS

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/hougesen/mdsf/releases/latest/download/mdsf-installer.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://github.com/hougesen/mdsf/releases/latest/download/mdsf-installer.ps1 | iex"

Cargo

Install using the published crate:

cargo install mdsf --locked

or directly from source:

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.

npm/npx

You can install mdsf using npm:

npm install -g mdsf-cli

mdsf format .

or run it directly using npx:

npx mdsf-cli format .

Homebrew

brew install hougesen/tap/mdsf

Usage

mdsf 0.3.2-dev
Format markdown code snippets using your favorite code formatters
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 old caches
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Formatting code

mdsf format file.md

Run formatters on input files

Usage: mdsf format [OPTIONS] [INPUT]...

Arguments:
  [INPUT]...  Path to files and/or directories

Options:
      --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                  Only format changed codeblocks
  -h, --help                   Print help
  -V, --version                Print version

Verifying code

mdsf verify docs/

Verify files are formatted

Usage: mdsf verify [OPTIONS] [INPUT]...

Arguments:
  [INPUT]...  Path to files and/or directories

Options:
      --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)
  -h, --help                   Print help
  -V, --version                Print version

Configuration

The default configuration of mdsf aims to as sane 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

mdsf supports running multiple formatters on the save code snippet.

{
  "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 209 tools. Feel free to open an issue/pull-request if your favorite tool/command is missing! 😃

Commands

mdsf currently supports 216 commands. Feel free to open an issue/pull-request if your favorite tool is missing! 😃

Shell completions

Shell completions can be generated using mdsf completions <SHELL>.

Generate shell completion

Usage: mdsf completions <SHELL>

Arguments:
  <SHELL>  [possible values: bash, elvish, fish, powershell, zsh]

Options:
  -h, --help     Print help
  -V, --version  Print version

Bash

Add the following to your .bashrc.

eval "$(mdsf completions bash)"

Bash

Add the following to your .zshrc.

eval "$(mdsf completions zsh)"

Fish

Add the following to ~/.config/fish/config.fish.

mdsf completions fish | source

PowerShell

Add the following to your PowerShell configuration (Can be found by running $PROFILE).

Invoke-Expression (&mdsf completions powershell)

Elvish

Add the following to ~/.elvish/rc.elv.

eval (mdsf completions elvish)

Acknowledgement

mdsf was inspired by the amazing neovim formatting plugin conform.nvim.

Alternatives to mdsf

• conform.nvim using injected mode.
• mdformat.