Markdown to JSON Converter: Practical Tips and Common Mistakes
Reviewed by the OnlineFree.app team · Updated
Key points
- Markdown to JSON Converter parses Markdown or GFM into a generic AST or a Notion-style block array.
- All parsing happens in the browser, so no document is uploaded and no account is needed.
- Choose the AST for prompts and RAG, and Notion blocks only when the destination is the Notion API.
- Turning pretty print off minifies the same data, which matters when the JSON becomes prompt context.
- Notion's block schema is narrower than Markdown, so rare constructs may be flattened or dropped.
What does Markdown to JSON Converter do?
Markdown to JSON Converter turns a Markdown or GFM document into a structured JSON tree — either a generic Markdown AST or a Notion-style block array — and it runs entirely in your browser, with no upload, no account and no rate limit.
The workflow is deliberately one screen. You paste your Markdown into the textarea, choose Markdown AST (JSON tree) or Notion blocks from the output-format selector, and the JSON result panel in Markdown to JSON Converter re-renders live as you type. A character and line count badge sits beside the input so you can see how much you pasted, and a Load sample link fills the box if you just want to inspect the shape of the output.
From there it is one click to Copy, or to Download .json, which produces document.json for the AST and notion-blocks.json for Notion blocks. The file is generated client-side through a Blob URL, so the download never leaves your machine. A small footer under the panel reports the node or element count, which is the fastest way to confirm your document parsed into real structure instead of one long text blob.
Markdown AST or Notion blocks: which should you pick?
Choose the Markdown AST for prompts, RAG chunks and custom renderers, and Notion blocks when the destination is the Notion API.
The AST keeps the document as a tree of typed nodes: headings, paragraphs, lists, list items, code blocks, blockquotes and tables, with inline markup such as bold, links and code spans stored as children of their parent node. That makes it easy to walk programmatically. Collect every heading node plus the text of the paragraph that follows it, and you already have a retrieval chunk with a title attached.
Notion blocks come back as a flatter array that mirrors the block types the Notion API accepts: headings become heading_1, heading_2 or heading_3, list items become bulleted_list_item or numbered_list_item, task list items become to_do with a checked boolean, and fenced code becomes code with a language field. The catch is that Notion's schema is narrower than Markdown. Heading levels 4 to 6, definition lists and other constructs that the CommonMark specification describes have no direct equivalent, so expect them to be flattened onto the nearest supported type. Read the first twenty or so blocks before you trust a large import.
Five mistakes that produce messy JSON
The most common mistake is pasting rendered text instead of Markdown source. If you copy from a preview pane or a rendered browser view, the asterisks, hashes and pipe characters are already gone, and the parser sees nothing but plain paragraphs. Copy from the raw file or the editor's source view.
The second is missing blank lines. Markdown blocks want a blank line between a paragraph and a following list, table or code fence; without it, a lazy continuation can absorb those lines into the previous paragraph. The third is mixing tabs and spaces inside nested lists. Indentation depth decides nesting, so pick one character and stay consistent for the whole document.
The fourth is an unclosed fenced code block. A fence opened with three backticks and never closed swallows the remainder of the document into a single code node, and the node count in the footer is the quickest way to spot it. The fifth is YAML frontmatter that does not start on line one: it must open with --- on the very first line and close with --- , with no leading blank line or byte-order mark, otherwise it parses as a thematic break followed by a paragraph. Raw inline HTML is preserved as text, so do not expect its attributes to become structure.
How do you keep JSON small enough for a prompt?
Turn pretty print off. Pretty print on gives you 2-space indentation and a readable multi-line document; off gives the identical data as a single minified line. The structure never changes, only the whitespace, but indentation characters still count when the JSON becomes prompt context.
Format choice matters too. A Notion-style array repeats a type key on every element, so it carries more fixed overhead per block than an AST, where the shape is already implied by nesting. If your target is a model rather than the Notion API, the AST is usually the leaner payload.
Measure rather than guess: paste both versions of the same document into the LLM Token Counter and compare. For retrieval workflows, a practical pattern is to split the Markdown at H2 boundaries before converting, so each converted chunk maps to one topic instead of one giant tree.
Where Markdown to JSON Converter stops
It is a parser and a serializer, not a renderer or an API client. It will not resolve link metadata, upload images, validate your JSON against the Notion API schema, or push anything into a workspace. There is also no saved history and no shareable result link, because nothing is stored anywhere. It is one of several free online tools on OnlineFree.app built to keep the whole operation inside the browser.
Very large documents are worth splitting. The result panel re-renders on each keystroke with a debounce, which is comfortable for a README or a note export, but multi-megabyte files will feel sluggish and are easier to handle in chunks.
Treat the output as a draft structure. Spot-check the first few nodes, confirm the node count matches what you expect from the source, and dry-run the import on a single page before migrating a whole wiki. If token budgets, block counts or table row counts matter to you, verify them against the source document rather than assuming the parse is perfect.
Frequently asked questions
Is Markdown to JSON Converter free, and do I need an account?
It is free and needs no account. The converter runs entirely in your browser at onlinefree.app, so there is no sign-up, no upload and no rate limit — you can paste, convert and copy as many documents as you like in a single session.
Does Markdown to JSON Converter send my document to a server?
No. Parsing happens client-side in JavaScript, so the Markdown you paste stays in the browser tab, and the Download .json button creates the file from a Blob URL instead of a server round trip. You can confirm this by watching the network tab in your browser's developer tools while you convert a document.
Can I use Markdown to JSON Converter to build Notion API payloads?
Yes. Set the output format to Notion blocks and the result is an array that mirrors Notion's block types, including to_do blocks with a checked flag for task lists and code blocks with a language field. The tool does not call the Notion API or validate against your workspace, so test the payload on one page before migrating a whole wiki.
What is the difference between pretty print on and off?
Pretty print on returns 2-space indented JSON that is easy to read and diff; off returns the identical data minified onto a single line. The structure never changes, only the whitespace. Turn it off when the JSON is context for a model or another program, and leave it on when you want to inspect the tree by eye.
Does Markdown to JSON Converter support tables, task lists and frontmatter?
Yes. It accepts GitHub Flavored Markdown, so tables, task lists, fenced code blocks, blockquotes and inline HTML all parse into structure. YAML frontmatter is recognised when it opens with --- on line one and closes with --- with no blank line before it. Rare constructs and inconsistent list indentation are the usual sources of surprising output, so compare the node count with what the source suggests.