Import Markdown Into WordPress as Real Blocks

A year ago the Markdown that reached a WordPress site was mostly README files and the odd developer's notes. Now it is the default output of every AI assistant, the export format of Notion, the native format of Obsidian, and what half of all documentation tooling produces. A lot of people have a .md file and a WordPress site and no clean way to get one into the other.

WordPress does not read Markdown. Here is what actually happens when you try, and the route that works.

What happens if you just paste it

Copy Markdown from a text editor and paste it into the block editor, and something surprising happens: it partly works. Gutenberg detects Markdown-looking plain text on paste and runs it through a converter. Headings become heading blocks, **bold** becomes bold, lists become lists.

Then the problems start.

Every single line break becomes a <br>. The converter is set to treat one newline as a hard break. Markdown written the normal way, with paragraphs wrapped at 80 characters or with a newline after each sentence, arrives as paragraphs full of forced line breaks in the wrong places. On a wide screen it looks like a poem.

Front matter becomes a paragraph. Anything between the --- lines at the top, Obsidian's tags, Notion's properties, is pasted in as visible text.

There is no title. You paste, then you go back and type the title, and if the document had one as its first heading you now have it twice.

Images vanish. An ![alt](path) line either disappears or becomes an empty image block, depending on the path.

You are in the editor with no preview. A 3,000-word document has just landed in a post. If it went wrong, you are fixing it block by block or deleting it and trying again.

Pasting from Notion or Obsidian directly is different again, and worse: those apps put HTML on the clipboard, not Markdown, so you get their markup with their classes and their nesting.

For a three-paragraph note, pasting is fine. For anything you would call a document, it is not.

What about Markdown plugins?

There are good Markdown plugins for WordPress, and most of them solve a different problem. Jetpack's Markdown module and WP Githuber MD let you write Markdown inside WordPress: they store the Markdown and render it on the front end. That is an editing workflow, and it is a good one if you want it.

Importing a file that already exists is a separate job. You have the document; you want it to become an ordinary WordPress post made of ordinary blocks that anyone on your team can edit afterwards, with no Markdown left in the database and no plugin needed to render it. That is what the rest of this post is about.

The route that works

DocxToPost, the free plugin behind DocxToWP, has read Word documents since it launched. From version 1.2.0 it reads Markdown too, through exactly the same upload, preview and publish flow.

The important thing is what comes out the other end: real blocks. Each heading is a Heading block, each list a List block, each table a Table block, each fenced code sample a Code block. Nothing is left as one lump of HTML. You could deactivate the plugin the next day and the post would be unaffected, because there is nothing in it that depends on the plugin.

Step by step

1. Install the plugin. In WordPress, Plugins → Add New, search for DocxToPost, install, activate. Check the version on the Plugins screen is 1.2.0 or later.

2. Get your content into a .md file.

• ChatGPT, Claude or another assistant: use the copy button on the response, paste into any text editor, save as post.md. The copy button gives you Markdown, not rendered text, which is what you want.
• Notion: on the page menu, Export → Markdown & CSV. You get a zip with the .md file and a folder of images. Unzip it.
• Obsidian: the note is already a .md file in your vault folder. Use it directly.
• GitHub or a docs repo: download the raw file.

3. Upload it. Open DocxToPost from the admin menu and drop the .md file on the upload area. The same screen takes an optional featured image. Click Convert & Preview.

4. Read the preview. The first # Heading in the file has become the post title and is no longer repeated in the body. If the file had front matter with a title:, that is used instead. If it had neither, the title comes from the filename, tidied up.

Above the content there may be a notice. Read it. It lists anything the importer had to leave out, which for Markdown means images with relative paths. More on that below.

5. Choose where it goes. Post type, status, author, categories, tags, slug, excerpt. Everything a normal post has. Then Publish, or Save Draft if you want to look at it in the editor first.

6. Open it in the block editor. Every element is its own block. Click a code sample and it is a Code block. Click a table and it is a Table block with the column alignment from your Markdown intact.

That is the whole process. Under a minute for a typical document.

What comes through

Raw HTML inside the Markdown is allowed through the same filter WordPress applies to every post, so ordinary tags survive and scripts do not.

What does not, and what to do about it

Being clear about this is more useful than pretending otherwise.

Images with relative paths. ![Diagram](images/architecture.png) refers to a file next to the Markdown. You uploaded one file, so there is nothing to resolve that against. The image is left out rather than left broken, and the preview notice names every one. Upload them to the Media Library and add them in the editor. Notion exports and GitHub READMEs are where this comes up most; a document from ChatGPT usually has no images at all.

Front matter beyond the title. slug:, categories:, tags:, date: are removed with the block and not read. The free plugin does one thing with front matter, which is the title. Set the rest on the preview screen.

Obsidian's own syntax. [[Wikilinks]] arrive as the literal text in double brackets, because they point at other notes in your vault, not at URLs. Callouts (> [!note]) become ordinary blockquotes with the marker as the first line. Replace links before you export, or fix them in the editor.

Task lists. - [ ] item is a GitHub extension, not core Markdown. It comes through as a list item starting with [ ].

Footnotes, math, Mermaid. Footnote references come through as text. Maths in $…$ is left as typed. A Mermaid diagram in a code fence becomes a Code block containing the Mermaid source, which is the right result if you have a Mermaid plugin and a plain code sample if you do not.

Many files at once. One file per upload. Pro's bulk import handles .docx only at the moment.

Notes for the common sources

From an AI assistant. This is the cleanest case. The output is well-formed Markdown, headings are real headings, code fences carry a language hint, and there are no images. One thing to check: assistants often start with a # heading that repeats your prompt rather than titling the piece. That heading becomes the post title, so edit it on the preview screen if it is not what you want.

From Notion. The exported filename carries a long hash (My Page 3f2a9c….md), but the title comes from the # heading Notion puts at the top, so you do not see the hash. If the page lived in a database, its properties are written as plain lines under that heading (Status: Done, Tags: …) and come through as a short paragraph; delete it in the editor. Images are in a sibling folder and need uploading by hand.

From Obsidian. Front matter with tags and aliases is removed. Wikilinks and callouts need attention, as above. Everything else, including nested lists and code, comes through cleanly.

From a GitHub README. Badges are usually images with absolute URLs and survive as external images. Relative links to other files in the repository become dead links, since the post is not in the repository.

Questions people ask

Can WordPress import a Markdown file on its own? No. Uploading a .md file to the Media Library stores it as a file attachment. Pasting the text into the block editor converts some of it, with the line-break problem, no title or metadata, and no images.

Which Markdown features are supported? Headings, paragraphs, bold, italic, strikethrough, inline code, links, ordered and unordered lists with nesting, blockquotes, tables with column alignment, horizontal rules, and fenced or indented code. Fenced code becomes a real Code block.

What happens to images? Full https:// URLs are kept as external images. Relative paths cannot be resolved from a single uploaded file, so those images are left out and listed on the preview screen.

Is front matter supported? The block is removed rather than shown, and title: becomes the post title. Other keys are not read in the free plugin.

Can I import many Markdown files at once? Not yet. One file at a time in the free plugin, and Pro's bulk import is .docx only at the moment.

Does it cost anything? No. Markdown import is in the free plugin, with no cap on how many files you convert.

The short version

Save it as .md. Upload it. Read the notice. Publish.

If you have been pasting AI output into WordPress and fixing the line breaks by hand, this is the part of the job you can stop doing.

---

Working from Word rather than Markdown? The same process for .docx files, including what to fix in the document first.