Giter Club home page Giter Club logo

mdsf's Introduction

mdsf

Format markdown code snippets using your favorite code formatters.

mdsf 0.2.3
Format markdown code snippets using your favorite code formatters
Mads Hougesen <[email protected]>

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

Installation

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

Cargo

Install using the published crate:

cargo install mdsf --locked

or directly from source:

git clone [email protected]:hougesen/mdsf.git

cargo install --path ./mdsf --bin mdsf

Usage

mdsf format <NAME_OF_FOLDER_OR_FOLDER>
Run formatters on input files

Usage: mdsf format [OPTIONS] <PATH>

Arguments:
  <PATH>  Path to file or directory

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

Verify code is formatted

mdsf verify <NAME_OF_FOLDER_OR_FOLDER>
Verify files are formatted

Usage: mdsf verify [OPTIONS] <PATH>

Arguments:
  <PATH>  Path to file or directory

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.

{
  // Only run `ruff` on Python snippets,
  "python": "ruff",
  // Run `usort` on file and then `black`
  "python": ["usort", "black"],
  // Run `usort`, if that fails run `isort`, finally run `black`
  "python": [["usort", "isort"], "black"]
}

Supported tools

Note

mdsf is not a package manager.

Only tools that are already installed will be used.

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

Formatter Description
alejandra https://github.com/kamadorueda/alejandra
ameba https://github.com/crystal-ameba/ameba
asmfmt https://github.com/klauspost/asmfmt
astyle https://astyle.sourceforge.net
auto-optional https://pypi.org/project/auto-optional/
autocorrect https://github.com/huacnlee/autocorrect
autoflake https://github.com/pycqa/autoflake
autopep8 https://pypi.org/project/autopep8/
beautysh https://pypi.org/project/beautysh/
bicep_format https://github.com/Azure/bicep
biome https://biomejs.dev
biome_check https://biomejs.dev
biome_lint https://biomejs.dev
black https://github.com/psf/black
blade-formatter https://github.com/shufo/blade-formatter
blue https://blue.readthedocs.io/en/latest/
bpfmt https://source.android.com/docs/setup/reference/androidbp
brittany https://github.com/lspitzner/brittany
bsfmt https://github.com/rokucommunity/brighterscript-formatter
buf https://buf.build/docs/reference/cli/buf/format
buildifier https://github.com/bazelbuild/buildtools
cabal_format https://www.haskell.org/cabal/
caramel_fmt https://caramel.run
clang-format https://docs.kernel.org/process/clang-format.html
clang-tidy https://clang.llvm.org/extra/clang-tidy
cljstyle https://github.com/greglook/cljstyle
codespell https://github.com/codespell-project/codespell
crlfmt https://github.com/cockroachdb/crlfmt
crystal_format https://crystal-lang.org/
csharpier https://csharpier.com/
css-beautify https://github.com/beautifier/js-beautify
csscomb https://github.com/csscomb/csscomb.js
d2 https://d2lang.com/
dart_fix https://dart.dev/tools/dart-fix
dart_format https://dart.dev/tools/dart-format
dcm_fix https://dcm.dev/docs/cli/fix/
dcm_format https://dcm.dev/docs/cli/format/
deno_fmt https://docs.deno.com/runtime/manual/tools/formatter
deno_lint https://docs.deno.com/runtime/manual/tools/linter
dfmt https://github.com/dlang-community/dfmt
dhall https://dhall-lang.org/
djlint https://www.djlint.com/
docformatter https://pypi.org/project/docformatter/
docstrfmt https://pypi.org/project/docstrfmt/
dotenv-linter https://github.com/dotenv-linter/dotenv-linter
dprint https://dprint.dev
easy-cofing-standard https://github.com/easy-coding-standard/easy-coding-standard
efmt https://github.com/sile/efmt
elm-format https://github.com/avh4/elm-format
erb-formatter https://github.com/nebulab/erb-formatter
erlfmt https://github.com/WhatsApp/erlfmt
eslint https://eslint.org
fantomas https://github.com/fsprojects/fantomas
findent https://pypi.org/project/findent/
fish_indent https://fishshell.com/docs/current/cmds/fish_indent.html
fixjson https://github.com/rhysd/fixjson
floskell https://github.com/ennocramer/floskell
fnlfmt https://git.sr.ht/~technomancy/fnlfmt
forge_fmt https://docs.rs/forge-fmt/latest/forge_fmt/
fourmolu https://hackage.haskell.org/package/fourmolu
fprettify https://github.com/fortran-lang/fprettify
gci https://github.com/daixiang0/gci
gdformat https://github.com/scony/godot-gdscript-toolkit
gersemi https://github.com/blankspruce/gersemi
gleam_format https://gleam.run/
gluon_fmt https://github.com/gluon-lang/gluon
gofmt https://pkg.go.dev/cmd/gofmt
gofumpt https://github.com/mvdan/gofumpt
goimports https://pkg.go.dev/golang.org/x/tools/cmd/goimports
goimports-reviser https://github.com/incu6us/goimports-reviser
golines https://github.com/segmentio/golines
google-java-format https://github.com/google/google-java-format
grain_format https://grain-lang.org
haml-lint https://github.com/sds/haml-lint
hfmt https://github.com/danstiner/hfmt
hindent https://hackage.haskell.org/package/hindent
html-beautify https://github.com/beautifier/js-beautify
htmlbeautifier https://github.com/threedaymonk/htmlbeautifier
imba_fmt https://github.com/imba/imba
isort https://pycqa.github.io/isort/
joker https://github.com/candid82/joker
js-beautify https://github.com/beautifier/js-beautify
jsona_format https://github.com/jsona/jsona
jsonnetfmt https://jsonnet.org/learning/tools.html
juliaformatter.jl https://github.com/domluna/JuliaFormatter.jl
just_fmt https://github.com/casey/just
kcl_fmt https://www.kcl-lang.io/docs/tools/cli/kcl/fmt
kdlfmt https://github.com/hougesen/kdlfmt
ktfmt https://github.com/facebook/ktfmt
ktlint https://github.com/pinterest/ktlint
leptosfmt https://github.com/bram209/leptosfmt
liquidsoap-prettier https://github.com/savonet/liquidsoap-prettier
luaformatter https://github.com/Koihik/LuaFormatter
markdownlint https://github.com/davidanson/markdownlint
markuplint https://markuplint.dev
mdformat https://github.com/executablebooks/mdformat
misspell https://github.com/client9/misspell/
mix_format https://hexdocs.pm/mix/main/Mix.Tasks.Format.html
nickel_format https://nickel-lang.org
nimpretty https://github.com/nim-lang/nim
nixfmt https://github.com/serokell/nixfmt
nixpkgs-fmt https://github.com/nix-community/nixpkgs-fmt
nph https://github.com/arnetheduck/nph
npm-groovy-lint https://github.com/nvuillam/npm-groovy-lint
ocamlformat https://github.com/ocaml-ppx/ocamlformat
ocp-indent https://github.com/OCamlPro/ocp-indent
ormolu https://hackage.haskell.org/package/ormolu
oxlint https://oxc.rs
packer_fmt https://developer.hashicorp.com/packer/docs/commands/fmt
perltidy https://github.com/perltidy/perltidy
pg_format https://github.com/darold/pgFormatter
php-cs-fixer https://github.com/PHP-CS-Fixer/PHP-CS-Fixer
phpcbf https://phpqa.io/projects/phpcbf.html
phpinsights https://phpinsights.com/
pint https://github.com/laravel/pint
prettier https://github.com/prettier/prettier
pretty-php https://github.com/lkrms/pretty-php
prisma https://prisma.io/
puppet-lint https://github.com/puppetlabs/puppet-lint
purs-tidy https://github.com/natefaubion/purescript-tidy
pycln https://github.com/hadialqattan/pycln
pyink https://github.com/google/pyink
qmlfmt https://github.com/jesperhh/qmlfmt
raco_fmt https://docs.racket-lang.org/fmt/
refmt https://reasonml.github.io/docs/en/
rescript_format https://rescript-lang.org/
roc_format https://github.com/roc-lang/roc
rstfmt https://github.com/dzhu/rstfmt
rubocop https://github.com/rubocop/rubocop
rubyfmt https://github.com/fables-tales/rubyfmt
ruff https://docs.astral.sh/ruff/formatter/
ruff_check https://docs.astral.sh/ruff/linter/
rufo https://github.com/ruby-formatter/rufo
rune_fmt https://github.com/rune-rs/rune
rustfmt https://github.com/rust-lang/rustfmt
rustywind https://github.com/avencera/rustywind
scalafmt https://github.com/scalameta/scalafmt
shfmt https://github.com/mvdan/sh
sleek https://github.com/nrempel/sleek
smlfmt https://github.com/shwestrick/smlfmt
snakefmt https://github.com/snakemake/snakefmt
sql-formatter https://github.com/sql-formatter-org/sql-formatter
sqlfluff https://github.com/sqlfluff/sqlfluff
sqlfmt https://sqlfmt.com
standardjs https://standardjs.com/
standardrb https://github.com/standardrb/standard
stylefmt https://github.com/matype/stylefmt
stylelint https://github.com/stylelint/stylelint
stylish-haskell https://github.com/haskell/stylish-haskell
stylua https://github.com/JohnnyMorganz/StyLua
swift-format https://github.com/apple/swift-format
swiftformat https://github.com/nicklockwood/SwiftFormat
taplo https://github.com/tamasfe/taplo
templ https://templ.guide
terraform_fmt https://www.terraform.io/docs/cli/commands/fmt.html
tlint https://github.com/tighten/tlint
tofu_fmt https://opentofu.org/docs/cli/commands/fmt/
topiary https://github.com/tweag/topiary
ts-standard https://github.com/standard/ts-standard
twig-cs-fixer https://github.com/VincentLanglet/Twig-CS-Fixer
typos https://github.com/crate-ci/typos
uiua_fmt https://github.com/uiua-lang/uiua
usort https://github.com/facebook/usort
veryl_fmt https://github.com/veryl-lang/veryl
vlang_fmt https://vlang.io
xmlformat https://github.com/pamoller/xmlformatter
xmllint http://xmlsoft.org/xmllint.html
xo http://github.com/xojs/xo
yamlfix https://github.com/lyz-code/yamlfix
yamlfmt https://github.com/google/yamlfmt
yapf https://github.com/google/yapf
yew-fmt https://github.com/its-the-shrimp/yew-fmt
zigfmt https://ziglang.org/
zprint https://github.com/kkinnear/zprint

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

mdsf's People

Contributors

dependabot[bot] avatar hougesen avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

mdsf's Issues

Add support for "http"

Here is the documentation of an http request

```http
POST /login HTTP/1.1
Authorization: Bearer bar
Content-Type: application/json

{
"foo": true}
```

Here is a reply

````mardown
```http
HTTP 200 OK
Content-Type: application/json

{"success":      true  }

```

But it's not limited to json replies. It could return HTML/XML

It's a very used pattern in API documentation

The code snippets are badly indented on purpose.

report issue somehow

Your code is a markdown code snippet formatter. That's the project purpose OK.

Your code is formatting block that could be invalid.

So your code is somehow also a linter, as you are able to know when you are facing an error when formatting a code block.

In debug mode I can see the code that are invalid (or with an strafe, I'm unsure)

What about reporting something like a warning aside file names to say you face x errors when processing a file.

issue shell block quote is not always directly about formatting shell scripts

shfmt is made for formatting script, definitely.

```shell
#!/bin/env bash

    date
```

But shell block quote in markdown is not ONLY about that

Yes, this would be valid

```shell
  cp   foo    bar
  touch   foo
```

But the alternative syntax used in many markdown linters is this one

$ command
result

So this

```shell
$ date
Tue Apr  2 23:54:37 CEST 2024
```

Please note this one is sometimes refered as console

```console
$ date
Tue Apr  2 23:54:37 CEST 2024
```
```console
foo@bar:~$ whoami
foo
```

So your script will try to format things that are not always script.

Feature request: implement a timeout when running formatter

Your code launches formatter on each code snippet.

Based on what I can see the code is extracting the code snippet, look for the header, then call the formatter according to the one available

I was struggling with some files formating that were taking 700s to be formatted.

When I moved the file in /tmp/ it was instant.

I used strace to identify the issue. At first I thought the code was looking for tons of files because of a bug in discovering foldes.

It appears the code calls npx to launch formatter such as sqlformatter

npx relies on node_modules, so when the files were in a repository that needs a private npm registry, AND my VPN is down. It will try over and over to reach the npm registry that cannot be reached.

When I switched my VPN on, the mdsf was able to format instantly.

TL;DR; This should be considered as a source of problem. I think you should implement at timeout setting (that maybe configured) this was when formatting a file you could stop processing and inform a user there were an error.

Feature request: add a verbose (or debug mode)

It would be interesting to be able to see the formatter that is running on each file

Of course, it would be only something to ask on demand.

maybe like a -v that inform that block from line X to Y is sent to prettier/shfmt.

with a -vv the information would be more details with the block content before calling the method, then after/ but also the exact path of the formatter used.

it could also be a kind of log level info/warn/error/debug

mdsf applies changes outside code snippet

I love your tool idea.

I can see you are actively working on it, so first of all, thank you !

Here are the kind of replacement I noticed

# title

Let's play!

Have some fun...

I like "mdsf"

| Field            | Description            |
|------------------|------------------------|
| foo              |   foo field            |
| bar              |   bar field            |

```shell
ls
```

will become

# title

Let’s play!

Have some fun…

I like “mdsf”

|Field|Description|
|-----|-----------|
|foo|foo field|
|bar|bar field|

```shell
ls
```

The table formatting is broken. It will render OK in markdown, but the text was altered.

You might not notice at first but it replaces:

  • ... (three consecutive dots) into U+2026 … HORIZONTAL ELLIPSIS
  • simple quote by U+2019 ’ RIGHT SINGLE QUOTATION MARK
  • double quoted text by text surrounded by:
    • U+201D ” RIGHT DOUBLE QUOTATION MARK
    • U+201C “ LEFT DOUBLE QUOTATION MARK

I would expect the code to only apply changes on the block quotes

Report missing formatter

Following #158 idea

Another interesting idea could be to be able to report when our code found block code you could have checked/formatted but you couldn't because the parser is not available.

My point is the fact someone may install your tool, but nothing else.

It will launch mdsf on his markdown files, but it will provide nothing.

So maybe, something you could report at the end as a warning.

invalid JSON is being produced once formatted

Here is a content that is wrongly formatted

This is the content of a markdown file

```json
{
        "foo": "bar",
        "user_id": "2313",
        "scope": ["internal"]
}
```
This is the content of a markdown file

```json
{
  "foo": "bar",
  "user_id": "2313",
  "scope": ["internal"],
}
```

The extra comma at the end of the list lead to an invalid json

Here is my mdsf.json

{
  "$schema": "https://raw.githubusercontent.com/hougesen/mdsf/main/schemas/v0.0.2/mdsf.schema.json",
  "json": {
    "enabled": true,
    "formatter": [
      [
        "prettier"
      ]
    ]
  }
}

prettier 3.2.5 is installed and work well.

golang formatter: problem when code snippet is not a full file

```go
var err = errors.New("dddd")

type Whatever struct {
     StartAt                time.Time  `json:"start_at"`
                End                time.Time  `json:"end_at"`
    Delete bool `json:-"`
}
```

golang can only be formatted with tools if the file is valid.

So if the linting doesn't work you can try to add this to the begining of the file

```go
package main

// REMOVE ANYTHING ABOVE THIS

var err = errors.New("dddd")

type Whatever struct {
     StartAt                time.Time  `json:"start_at"`
                End                time.Time  `json:"end_at"`
    Delete bool `json:-"`
}
```

mdsf will then be able to format like this

```go
package main

// REMOVE ANYTHING ABOVE THIS

var err = errors.New("dddd")

type Whatever struct {
	StartAt time.Time `json:"start_at"`
	End     time.Time `json:"end_at"`
	Delete  bool      `json:-"`
}
```

Then if you trim the code then

```go
var err = errors.New("dddd")

type Whatever struct {
	StartAt time.Time `json:"start_at"`
	End     time.Time `json:"end_at"`
	Delete  bool      `json:-"`
}
```

It would be a more fail proof hack but quite an hack

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.