Ultimate Guide: How to Use MarkConvert
MarkConvert is the ultimate browser-based Markdown conversion tool. It is 100% private, requiring no server uploads, and works entirely offline once loaded. Here is a comprehensive guide to its features.
1. Choose Your Output Format
Select from 5 different output formats using the chips at the top:
- HTML: Generates clean, styled HTML. Choose between GitHub, Minimal, or Modern themes.
- PDF-HTML: Generates HTML optimized for printing to PDF with
@page CSS rules for perfect page breaks.
- Notion JSON: Converts Markdown to Notion's Block API JSON. Excellent for importing tables, checkboxes, and callouts into Notion without data loss.
- Obsidian: Cleans up Markdown and ensures Obsidian-flavored callouts (
> [!NOTE]) and frontmatter are correct.
- Plain MD: Formats and cleans your raw Markdown.
- Preview: See a live render of your document.
2. Advanced Markdown Features
MarkConvert fully supports GitHub Flavored Markdown (GFM), including tables and task lists. Additionally, it supports:
- Mermaid Diagrams: Simply use a
```mermaid code block to render flowcharts and sequence diagrams in the Preview mode.
- KaTeX Math: Use
$$ for block equations or $ for inline math. It will be rendered beautifully in the preview and correctly translated to Notion Equation blocks.
3. Local Image Embedding (Data URLs)
Click the Embed Image button to select an image from your computer. MarkConvert will convert it to a Base64 Data URL and embed it directly into your Markdown text. This ensures your output file is completely self-contained without needing external image hosting.
4. Privacy & History
Because MarkConvert is a pure client-side web application, your data never leaves your device. Your recent documents are saved in your browser's localStorage, which you can access via the History button. You can safely convert confidential work documents or API keys without fear of data leaks.
How to Import Markdown into Notion with Full Fidelity
Notion accepts Markdown via paste or file import, but its parser is surprisingly simplistic. GFM tables are dropped entirely, multi-level lists collapse, callout blocks don't exist, and task checkboxes lose their checked state.
The Solution: Notion JSON
The correct approach is to convert Markdown to Notion's native Block API JSON format first, then import the structured data. MarkConvert does this entirely in your browser — no API key, no account required.
h1, h2, h3 → heading_1/2/3 blocks- Task lists (
- [ ]) → to_do blocks with checked state
- GFM Tables →
table with table_row children
- Callouts (
> [!NOTE]) → callout blocks with emoji icons
Step-by-Step Guide
1. Open MarkConvert and paste your Markdown.
2. Select Notion JSON output.
3. Copy the output and use the Notion API (PATCH /blocks) or a local script to push the blocks.
Your document never leaves your browser.
Obsidian ↔ Notion: The Complete Conversion Playbook
Both Obsidian and Notion use Markdown as their foundation, but they've each extended it in incompatible directions. Understanding where they differ is the key to lossless conversion.
Callouts and Links
Obsidian uses > [!NOTE] Title syntax. Notion renders a native Callout block. MarkConvert automatically maps Obsidian's 12 standard callout types to Notion callouts with matching emojis.
> [!WARNING] Watch out!
> This is an Obsidian callout.
Obsidian to Notion
Paste your vault note into MarkConvert. Select Notion JSON. Wikilinks are preserved as plain text (since Notion uses internal block IDs). Callouts and tables are perfectly mapped.
Convert Markdown to Beautiful PDFs Locally — No LaTeX Required
Chrome's print-to-PDF engine is incredibly capable. With correct @page CSS rules, you can control page size, margins, headers, footers, page numbering, and widow/orphan control.
Browser-Based PDF Generation
MarkConvert's PDF-ready HTML output includes a complete, self-contained HTML file with all necessary print CSS pre-configured. No LaTeX. No headless browser.
@page { size: A4; margin: 2cm; }page-break-before: always on H2 headers- Print-optimized serif fonts and high-contrast colors
Just download the HTML, open it in Chrome, and press Ctrl+P (Print to PDF). Ensure "Background graphics" is checked.
Embedding Mermaid Diagrams and KaTeX in Notion
Notion doesn't render Mermaid natively. MarkConvert solves this by rendering the Mermaid diagram client-side to SVG, encoding it as a data URL, and embedding it as a Notion image block.
KaTeX Math
Notion has a native equation block type. MarkConvert detects $...$ inline math and $$...$$ display math and emits the correct Notion block types automatically.
Everything runs in your browser. No external APIs are called to render your proprietary diagrams.
Why Your Markdown Tool Should Never Touch a Server
Most online converters upload your documents to a remote server for processing. This exposes personal notes, work documents, source code, and API keys to potential breaches or data logging.
The MarkConvert Difference
Every conversion in MarkConvert happens via pure JavaScript running in your browser tab's sandboxed environment. The AST parser, Notion block mapper, and PDF generator all run locally.
You can verify this by opening your browser's Network tab. When you convert a document, exactly zero outbound network requests are made. Your data remains strictly yours.