Metadata-Version: 2.5
Name: mdformat-directives
Version: 0.0.1
Summary: An mdformat plugin for generic directives
Project-URL: Repository, https://github.com/terminalkitten/mdformat-directives
Project-URL: Issues, https://github.com/terminalkitten/mdformat-directives/issues
Author-email: terminalkitten <dk@terminalkitten.com>
License-Expression: MIT
License-File: LICENSE
Keywords: directives,formatter,markdown,markdown-it,mdformat
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Requires-Dist: mdformat>=1.0.0
Requires-Dist: mdit-py-plugins>=0.6.1
Provides-Extra: dev
Requires-Dist: mdformat-deflist>=0.1.4; extra == 'dev'
Requires-Dist: mdformat-gfm>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=9.1; extra == 'dev'
Requires-Dist: ruff>=0.17; extra == 'dev'
Requires-Dist: ty>=0.0.89; extra == 'dev'
Description-Content-Type: text/markdown

# mdformat-directives

An [mdformat](https://github.com/hukkin/mdformat) plugin for generic directives, the
`:::name[label]{key="value"}` syntax of [remark-directive](https://github.com/remarkjs/remark-directive)
and [dokk](https://github.com/terminalkitten/dokk):

```md
:::note[A title]{kind="info"}
Markdown inside is **formatted**; the fences stay where they are.
:::

::install[dokk[search]]
```

Without it, mdformat sees `:::` as text: it pulls closing fences into lists and reflows the
blocks.

## Install

```sh
pipx install mdformat
pipx inject mdformat mdformat-directives
```

## Use

```sh
mdformat docs
```

- **Blocks** `:::name` (three or more colons) are kept, with the Markdown inside formatted. To
  nest, give the outer block more colons; the count is kept.
- **One-line directives** `::name[label]{attrs}` are kept as written.
- **Text directives** such as `:badge[New]{variant="secondary"}` are kept as written, also
  where another plugin would escape their colon.

## Raw blocks

Some blocks hold data, not Markdown, such as `.env` lines whose columns line up. Keep their body
exactly as written in `.mdformat.toml`:

```toml
[plugin.directives]
raw = ["env", "bench"]
```

or on the command line: `mdformat --raw-directives env,bench docs`.

## Development

```sh
uv sync --all-extras
make lint   # ruff fix and format, ty, pytest
```

### Releasing

The version comes from the git tag (hatch-vcs); there is nothing to bump. Push a tag such as
`v0.1.0` and `.github/workflows/release.yml` builds the wheel and sdist and tests the wheel. Once
the `pypi` environment is approved, it publishes to PyPI and creates the GitHub release.

Before the first release, on PyPI add a trusted publisher (pending publisher) for this repository,
workflow `release.yml`, environment `pypi`; on GitHub create the `pypi` environment with a
required reviewer (Settings > Environments).
