Metadata-Version: 2.4
Name: mdformat_obsidian
Version: 0.3.1
Summary: Format Markdown for Obsidian including Callouts (Admonitions)
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: hypothesis>=6.100.0 ; extra == 'test'
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]

An [mdformat](https://github.com/executablebooks/mdformat) plugin for [Obsidian Flavored Markdown](https://help.obsidian.md/Editing+and+formatting/Obsidian+Flavored+Markdown).

## Features

- **[Callouts](https://help.obsidian.md/Editing+and+formatting/Callouts)** - Alert-style blocks with custom titles and folding
    - Supports all standard callout types (note, tip, warning, etc.)
    - Custom callout types with any identifier
    - Foldable callouts with `-` or `+` indicators
    - Nested callouts
    - Case-insensitive type matching (normalized to uppercase for compatibility)
- **Inline Footnotes** - Obsidian's `^[inline footnote]` syntax
- **Task Lists** - Extended checklist markers beyond `[x]` and `[ ]`
    - Supports `[?]`, `[/]`, `[-]`, and other custom markers
    - Preserves marker style during formatting
- **Dollar Math** - LaTeX math with `$...$` and `$$...$$` delimiters
    - Inline math: `$E=mc^2$`
    - Block math: `$$\n...\n$$`

> [!NOTE]
> The format for [GitHub Alerts](https://github.com/kyleking/mdformat-gfm-alerts) differs slightly from Obsidian callouts. Obsidian supports folding, custom titles, and is case-insensitive. For improved interoperability, this package normalizes callout types to uppercase (e.g., `[!tip]` → `[!TIP]`).

## `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 / prek

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

### uvx

```sh
uvx --with=mdformat-obsidian mdformat
```

Or with pipx:

```sh
pipx install mdformat
pipx inject mdformat mdformat-obsidian
```

## HTML Rendering

To generate HTML output, use `obsidian_plugin` from `mdit_plugins`. This combines all Obsidian-flavored markdown features (callouts, footnotes, task lists, math). For more details, see the [markdown-it-py documentation](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)
# <div>
# <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>
# </div>
```

**Accessibility Note:** For improved semantics, callouts are rendered as `<div>` elements rather than `<blockquote>`. The `>` syntax is repurposed for callouts (not quotations), so using div elements better represents the content structure. See [discussion on GitHub](https://github.com/orgs/community/discussions/16925#discussioncomment-8729846).

## Caveats

- **LaTeX Math**: Direct `\begin{...}` LaTeX environments are not supported. Use dollar math syntax (`$...$` or `$$...$$`) instead.
- **HTML Output Only**: The HTML rendering features are designed for programmatic HTML generation. For markdown-to-markdown formatting (the primary mdformat use case), these renderers are not invoked.
- **GitHub Compatibility**: While callouts work in both Obsidian and GitHub, subtle formatting differences exist. This plugin prioritizes Obsidian compatibility.

## Contributing

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

[ci-badge]: https://github.com/kyleking/mdformat-obsidian/actions/workflows/tests.yml/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
