mdsf-cli v0.8.1

mdsf

Format, and lint, markdown code snippets using your favorite tools.

Table of contents

• mdsf
  • Table of contents
  • Installation
    • Linux & MacOS
    • Windows
    • Cargo
    • npm/npx
    • Homebrew
    • Conda
  • Editor Support
    • Visual Studio Code
    • Vim / NeoVim
      • conform.nvim
  • Usage
    • Formatting code
    • Verifying code
    • GitHub workflow examples
      • Format and commit
      • Verify
    • treefmt
  • Configuration
    • Tools
    • Commands
  • Shell completions
    • Bash
    • Bash
    • Fish
    • PowerShell
    • Elvish
    • Nushell
  • 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

Conda

An unofficial (and unsupported) Conda package can be found at https://anaconda.org/conda-forge/mdsf.

conda install conda-forge::mdsf

Editor Support

Visual Studio Code

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 has native support for running mdsf.

local conform = require("conform")

conform.setup({
	formatters_by_ft = {
		markdown = { "mdsf" },
		-- ...
	},
	-- ...
})

Usage

mdsf 0.8.1
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

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

Verifying code

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 workflow examples

There are a lot of different ways to run mdsf using GitHub actions.

The easiest way, in my opinion, is to use an action like taiki-e/install-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.

Format and commit

This workflow formats your repository using mdsf and then commits the changes.

name: mdsf

on: push

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install mdsf
        uses: taiki-e/install-action@v2
        with:
          tool: mdsf

      - 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"

Verify

This workflow verifies your repository is formatted.

name: mdsf

on: push

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install mdsf
        uses: taiki-e/install-action@v2
        with:
          tool: mdsf

      - name: Run mdsf
        run: mdsf verify --log-level warn .

treefmt

Add the following to your treefmt.toml to run mdsf using treefmt.

# 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

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

| md-padding(https://github.com/harttle/md