mdsf

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

Table of contents
Installation
- Linux & MacOS
- Windows
- Cargo
- npm/npx
- Homebrew
- Conda
Usage
Configuration
Shell completions
- Bash
- Zsh
- Fish
- PowerShell
- Elvish
- Nushell
Rust MSRV
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

Usage

mdsf 0.12.0-next
Format, and lint, markdown code snippets using your favorite tools
Mads Hougesen <mads@mhouge.dk>

Usage: mdsf [OPTIONS] <COMMAND>

Commands:
  format       Run tools 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:
      --log-level <LOG_LEVEL>  [default: debug] [possible values: trace, debug, info, warn, error, off]
  -h, --help                   Print help
  -V, --version                Print version

Formatting code

The format command, as the name implies, is used to format documents.

mdsf format file.md

Run tools 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 file

      --debug
          Log stdout and stderr of formatters

      --threads <THREADS>
          Amount of threads to use.

          Defaults to 0 (auto).

      --cache
          Cache results

      --log-level <LOG_LEVEL>
          [default: debug]
          [possible values: trace, debug, info, warn, error, off]

      --timeout <TIMEOUT>
          Tool timeout in seconds.

          Defaults to no timeout.

      --on-missing-language-definition <ON_MISSING_LANGUAGE_DEFINITION>
          What to do when a codeblock language has no tools defined.

          Falls back to the value defined in your config file, if no argument is provided.

          [possible values: ignore, fail, fail-fast]

      --on-missing-tool-binary <ON_MISSING_TOOL_BINARY>
          What to do when the binary of a tool cannot be found.

          Falls back to the value defined in your config file, if no argument is provided.

          [possible values: ignore, fail, fail-fast]

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

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]

Options:
      --log-level <LOG_LEVEL>  [default: debug] [possible values: trace, debug, info, warn, error, off]
  -h, --help                   Print help
  -V, --version                Print version

Verifying code

You can verify that the document is formatted using the mdsf verify command.

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 file

      --debug
          Log stdout and stderr of formatters

      --threads <THREADS>
          Amount of threads to use.

          Defaults to 0 (auto).

      --timeout <TIMEOUT>
          Tool timeout in seconds.

          Defaults to no timeout.

      --log-level <LOG_LEVEL>
          [default: debug]
          [possible values: trace, debug, info, warn, error, off]

      --on-missing-language-definition <ON_MISSING_LANGUAGE_DEFINITION>
          What to do when a codeblock language has no tools defined.

          Falls back to the value defined in your config file, if no argument is provided.

          [possible values: ignore, fail, fail-fast]

      --on-missing-tool-binary <ON_MISSING_TOOL_BINARY>
          What to do when the binary of a tool cannot be found.

          Falls back to the value defined in your config file, if no argument is provided.

          [possible values: ignore, fail, fail-fast]

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

name: mdsf

on: push

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

      - name: Install mdsf
        uses: hougesen/mdsf@main

      - 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

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" },
		-- ...
	},
	-- ...
})

treefmt

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

# treefmt.toml

[formatter.mdsf]
command = "mdsf"
options = ["format"]
includes = ["*.md"]

pre-commit

See pre-commit for instructions

Sample .pre-commit-config.yaml:

repos:
  - repo: https://github.com/houges

Mdsf

Install / Use

README