Metadata-Version: 2.4
Name: mdformat_obsidian
Version: 0.2.0
Keywords: markdown,markdown-it,mdformat,mdformat_plugin_template
Author: kyleking
Author-email: kyleking <dev.act.kyle@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: mdformat>=0.7.19
Requires-Dist: mdformat-gfm>=1.0.0
Requires-Dist: mdit-py-plugins>=0.4.1
Requires-Dist: mdformat-beautysh>=0.1.1 ; extra == 'recommended'
Requires-Dist: mdformat-config>=0.2.1 ; extra == 'recommended'
Requires-Dist: mdformat-frontmatter>=2.0.8 ; extra == 'recommended'
Requires-Dist: mdformat-ruff>=0.1.3 ; extra == 'recommended'
Requires-Dist: mdformat-simple-breaks>=0.0.1 ; extra == 'recommended'
Requires-Dist: mdformat-web>=0.1.0 ; extra == 'recommended'
Requires-Dist: mdformat-wikilink>=0.2.0 ; extra == 'recommended'
Requires-Dist: setuptools ; extra == 'recommended'
Requires-Dist: pytest>=9.0.1 ; extra == 'test'
Requires-Dist: pytest-beartype>=0.2.0 ; extra == 'test'
Requires-Dist: pytest-cov>=7.0.0 ; extra == 'test'
Requires-Python: >=3.10.0
Project-URL: Bug Tracker, https://github.com/kyleking/mdformat-obsidian/issues
Project-URL: Changelog, https://github.com/kyleking/mdformat-obsidian/releases
Project-URL: homepage, https://github.com/kyleking/mdformat-obsidian
Provides-Extra: recommended
Provides-Extra: test
Description-Content-Type: text/markdown

# mdformat-obsidian

[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]

<!-- [![codecov.io][cov-badge]][cov-link]
[cov-badge]: https://codecov.io/gh/executablebooks/mdformat-obsidian/branch/main/graph/badge.svg
[cov-link]: https://codecov.io/gh/executablebooks/mdformat-obsidian
 -->

An [mdformat](https://github.com/executablebooks/mdformat) plugin for [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown). This plugin directly supports [Callouts](https://help.obsidian.md/Editing+and+formatting/Callouts), inline footnotes, task lists with custom markers, and dollar math. See the test directory for supported formats.

> [!NOTE]
> The format for [GitHub Alerts](https://github.com/kyleking/mdformat-gfm-alerts) differs slightly from Obsidian, so they are not fully compatible. Obsidian supports folding, custom titles, and is case insensitive. To improve interoperability, this package makes the stylistic choice of capitalizing the text within `[!...]`.

## `mdformat` 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 specifies an "extra" (`'recommended'`) for plugins that work well with `GFM`:

- [mdformat-beautysh](https://pypi.org/project/mdformat-beautysh)
- [mdformat-black](https://pypi.org/project/mdformat-black)
- [mdformat-config](https://pypi.org/project/mdformat-config)
- [mdformat-frontmatter](https://pypi.org/project/mdformat-frontmatter)
- [mdformat-simple-breaks](https://pypi.org/project/mdformat-simple-breaks)
- [mdformat-web](https://pypi.org/project/mdformat-web)
- [mdformat-wikilink](https://github.com/tmr232/mdformat-wikilink)

### Pre-Commit

```yaml
repos:
  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.18
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-obsidian
          # Or
          # - "mdformat-obsidian[recommended]"
```

### pipx

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

## HTML Rendering

To generate HTML output, `obsidian_plugin` can be imported from `mdit_plugins`. For more guidance on `MarkdownIt`, see the docs: <https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser>

```py
from markdown_it import MarkdownIt

from mdformat_obsidian.mdit_plugins import obsidian_plugin

md = MarkdownIt()
md.use(obsidian_plugin)

text = "> [!tip] Callouts can have custom titles\n> Like this one."
md.render(text)
# <blockquote>
# <div data-callout-metadata="" data-callout-fold="" data-callout="tip" class="callout">
# <div class="callout-title">
# <div class="callout-title-inner">Callouts can have custom titles</div>
# </div>
# <div class="callout-content">
# <p>Like this one.</p>
# </div>
# </div>
# </blockquote>
```

> [!WARNING]
> The outer `<blockquote>` tag is preserved to maintain compatibility with standard Markdown parsers. For full accessibility, you may want to replace this with a `<div>` in post-processing, as the `>` blockquote syntax is being repurposed for callouts.

## Contributing

See [CONTRIBUTING.md](https://github.com/KyleKing/mdformat-obsidian/blob/main/CONTRIBUTING.md)

[ci-badge]: https://github.com/kyleking/mdformat-obsidian/workflows/CI/badge.svg?branch=main
[ci-link]: https://github.com/kyleking/mdformat-obsidian/actions?query=workflow%3ACI+branch%3Amain+event%3Apush
[pypi-badge]: https://img.shields.io/pypi/v/mdformat-obsidian.svg
[pypi-link]: https://pypi.org/project/mdformat-obsidian
