Skip to content

Commit

Permalink
docs: add information on using the extra "recommended"
Browse files Browse the repository at this point in the history
  • Loading branch information
KyleKing committed Dec 21, 2022
1 parent e284aab commit c150553
Showing 1 changed file with 18 additions and 2 deletions.
20 changes: 18 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,24 @@ An [mdformat](https://github.com/executablebooks/mdformat) plugin for mkdocs.

> *Warning*
>
> This is an initial proof of concept. Non-list items nested within a list are not properly handled (i.e. nested code blocks, quotes, etc.). Please [open an issue](https://github.com/KyleKing/mdformat-mkdocs/issues/new) and share examples that aren't properly supported!
> This is an initial proof of concept. Non-list items nested within a list are not properly handled (i.e. nested code blocks, quotes, etc.). Please [open an issue](https://github.com/KyleKing/mdformat-mkdocs/issues/new) and share examples of any code that isn't properly formatted!
## Usage

Add this package wherever you use `mdformat` and the plugin will be auto-recognized. No additional configuration necessary. See [additional information on `mdformat` plugins here](https://mdformat.readthedocs.io/en/stable/users/plugins.html)

Tip: this package has a pip extra, `recommended`, of plugins that work well with mkdocs:

- mdformat-admon
- mdformat-beautysh
- mdformat-black
- mdformat-config
- mdformat-frontmatter
- mdformat-gfm
- mdformat-tables
- mdformat-toc
- mdformat-web

### Pre-commit

```yaml
Expand All @@ -27,19 +39,23 @@ repos:
- id: mdformat
additional_dependencies:
- mdformat-mkdocs
# Or
# - "mdformat-mkdocs[recommended]"
```

### pipx

```sh
pipx install mdformat
pipx inject mdformat mdformat-mkdocs
# Or
# pipx inject mdformat-gfm "mdformat-mkdocs[recommended]"
```

## Caveats

- All indents are converted to 4-spaces
- This plugin converts all bulleted items to dashes and numerals to `1.`
- This plugin converts all bulleted items to dashes (`-`) and numerals to `1.`

See the example test files, [./tests/pre-commit-test.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/pre-commit-test.md) and [./tests/fixtures.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/fixtures.md)

Expand Down

0 comments on commit c150553

Please sign in to comment.