1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
# Installation and usage
```{include} ../../README.md
:start-after: <!-- start installing -->
:end-before: <!-- end installing -->
```
```{warning}
The formatting style produced by mdformat may change in each version.
It is recommended to pin mdformat dependency version.
```
```{include} ../../README.md
:start-after: <!-- start cli-usage -->
:end-before: <!-- end cli-usage -->
```
## Python API usage
### Format text
```python
import mdformat
unformatted = "\n\n# A header\n\n"
formatted = mdformat.text(unformatted)
assert formatted == "# A header\n"
```
### Format a file
Format file `README.md` in place:
```python
import mdformat
# Input filepath as a string...
mdformat.file("README.md")
# ...or a pathlib.Path object
import pathlib
filepath = pathlib.Path("README.md")
mdformat.file(filepath)
```
### Options
All formatting style modifying options available in the CLI are also available in the Python API,
with equivalent option names:
```python
import mdformat
mdformat.file(
"FILENAME.md",
options={
"number": True, # switch on consecutive numbering of ordered lists
"wrap": 60, # set word wrap width to 60 characters
}
)
```
## Usage as a pre-commit hook
`mdformat` can be used as a [pre-commit](https://github.com/pre-commit/pre-commit) hook.
Add the following to your project's `.pre-commit-config.yaml` to enable this:
```yaml
- repo: https://github.com/hukkin/mdformat
rev: 1.0.0 # Use the ref you want to point at
hooks:
- id: mdformat
# Optionally add plugins
additional_dependencies:
- mdformat-gfm
- mdformat-black
```
|
