# ForMaT Markdown
A diff-friendly Markdown formatter that breaks lines on
sensible punctuations and words to fit a line width.
This is more useful to use with Git than formatters like Prettier because
the formatting is more consistent, resulting in smaller diffs.
FMTM uses [FMTT][fmtt] to format Markdown paragraphs:
- Respect line width limit.
- Prioritize splitting on
1. sentence ends like `.`, then
1. sub-sentence ends like `,`, sub-sentence starts like `(`, and
sentence-connection words like `and`.
- Limited support for abbreviations using heuristics.
FMTM preserves code blocks, and trims leading spaces to a multiple of 4 for
display math and HTML blocks.
## Installation
```sh
cargo install fmtm
```
## Usage
```sh
$ fmtm --help
ForMaT Markdown diff-friendly,
breaking lines on sensible punctuations and words to fit a line width.
Like FMTT,
FMTM formats its input to have lines shorter than the line width limit
(if possible).
It reads an input file or StdIn and prints the formatted text to StdOut.
Like FMTT, FMTM only preserves leading spaces, not tabs.
Usage: fmtm [OPTIONS]
Options:
-w, --line-width <LINE_WIDTH>
Maximum line width limit. Preserve line lengths if set to 0.
[default: 80]
-f, --filename <FILENAME>
Name of input file; if omitted, read from StdIn.
-c, --change-in-place
If input file is provided, write output to it.
-e, --emphasis-marker <EMPHASIS_MARKER>
Marker for emphasis spans, or preserve the input if set to "".
[default: *]
-s, --strong-marker <STRONG_MARKER>
Marker for strong spans, or preserve the input if set to "".
[default: **]
-i, --indentation <INDENTATION>
Fixed indentation string,
or calculate to align the beginning of content text in each list if set to "".
[default: " "]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
```
## Examples
See [`src/tests/**.md`](/src/tests/) for test inputs and
their formatted output in [`src/tests/snapshots/`](/src/tests/snapshots/).
This documentation itself is also formatted with FMTM.
## Thanks
A fork of @ytmimi's [`markdown-fmt`](https://github.com/ytmimi/markdown-fmt)
powers this formatter's Markdown handling; it is a proof of concept for
`rustfmt`. Thank you @ytmimi for all the hard work!
## Future work
This formatter is for myself. If you want extra features, feel free to fork.
Pull Requests are welcome, but I will try to keep high code quality.
Items with 🌹 are the ones I want.
## Unexposed configurations
I have implemented these options in the `markdown-fmt` fork, but
have not exposed them in the CLI.
- [ ] Customize unordered list style.
Currently, it is fixed to `-`, but can be `*` or preserved.
- [ ] Customize ordered list style.
Currently, it is fixed to `1.`, but can have leading `0`s or be preserved.
## Near-term extensions
These extensions can be implemented simply by adding `struct`s that
implement traits in my `markdown-fmt` fork.
I lean towards calling external CLI applications (shell out) for
formatting these blocks of other languages.
- [ ] Format code blocks.
- [ ] Format HTML blocks 🌹.
- [ ] Format math expressions 🌹.
- [ ] Customize ordered list numbers to auto-increment. @ytmimi wanted this.
## Markdownlint compliance
These functionalities require further tweaking `markdown-fmt` itself.
- [ ] Only use fenced code blocks 🌹.
- [ ] Add `<` `>` around bare URLs 🌹.
- [ ] One blank line around each heading 🌹.
- [ ] One blank line around each code block 🌹.
Functionalities that alter the content would, in principle, not be implemented.
Examples include fixing reversed links and incrementing header levels.
Currently, it is perfectly fine to format a Markdown document with
both FMTM and Markdownlint, similar to running isort and black, except
the order does not matter.
[fmtt]: https://github.com/SichangHe/fmtt