mdformat-obsidian

An mdformat plugin for Obsidian Flavored Markdown.

Features

• 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 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

Tip: this package specifies an "extra" ('recommended') for plugins that work well with GFM:

• mdformat-beautysh
• mdformat-black
• mdformat-config
• mdformat-frontmatter
• mdformat-simple-breaks
• mdformat-web
• mdformat-wikilink

pre-commit / prek

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

uvx

uvx --with=mdformat-obsidian mdformat

Or with pipx:

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.

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.

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