mathdown

Converts LaTeX, PDFs, and images into Obsidian markdown with theorem callouts.

1|Updated May 9, 2026
One-click install
npx skills add https://github.com/shun-dong/mathdown --skill mathdown
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: mathdown
Source: https://github.com/shun-dong/mathdown/tree/main
Command: npx skills add https://github.com/shun-dong/mathdown --skill mathdown

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

It converts scattered mathematical materials into consistent Obsidian markdown, preserving block identity for reliable cross-file references.

Core Features & Use Cases

  • Multi-source math ingestion: Take LaTeX, web pages, PDFs, images/OCR, and existing markdown/text and normalize them into a unified Obsidian math-note format.
  • Stable block mapping for citations: Maintain and update a cross-reference block map (label → block_id) so \ref-style citations can be converted into [[file#^block_id]] reliably.
  • Math formatting discipline: Enforce strict rules for inline/display math, callout-based theorem/definition structure, TikZ-only diagram rendering, and conservative rewriting that avoids inventing unsupported claims.
  • Automated workflow support: Use provided scripts to preprocess LaTeX chapters (macro expansion, index cleanup), build the label map from converted markdown, and validate common conversion issues.

Quick Start

Ask the assistant to convert a LaTeX chapter file into Obsidian markdown following mathdown’s formatting rules and then update the unified label map so all cross-references resolve to stable block IDs.

Frequently Asked Questions about mathdown

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert LaTeX documents into Obsidian markdown notes?

You can convert LaTeX into Obsidian markdown by applying macro expansion, extracting labels, and formatting the content with strict inline/display math rules and callout-based theorem structures.

What is the best way to preserve cross-references when converting math PDFs to markdown?

The best way to preserve cross-references in markdown is by maintaining a unified label-to-block_id map, which converts LaTeX \ref-style citations into stable Obsidian [[file#^block_id]] links across multiple source types.

Can I ingest mathematical content from OCR images and web pages into a unified markdown format?

Yes, you can ingest math content from images/OCR, web pages, PDFs, and existing text, normalizing all sources into a unified Obsidian math-note format with consistent block identity for reliable citations.

Does mathdown validate converted markdown for formatting errors?

mathdown validates converted markdown by checking for residual LaTeX commands, balanced math delimiters, and callout correctness to ensure the final Obsidian notes maintain strict mathematical formatting discipline.

How do I build a stable block map for cross-file citations in Obsidian?

You can build a stable block map by using automated scripts to extract labels from converted markdown, creating a unified label-to-block_id map that reliably resolves cross-file citations across your math note corpus.