DOCX to WordPress Gutenberg blocks converter

What this does

WordPress stores posts as blocks. A block is ordinary HTML wrapped in a comment that tells the editor what kind of thing it is. A heading block looks like this:

<!-- wp:heading -->
<h2 class="wp-block-heading">Getting Started</h2>
<!-- /wp:heading -->

When you copy text out of Word and paste it into the editor, you usually do not get blocks. You get one Classic block holding the entire document, or a pile of paragraphs with Word styling stuck to them. Both are awkward to edit and both look wrong in your theme.

This tool reads the .docx file directly and writes the block markup for you. Headings become heading blocks, lists become list blocks with their nesting intact, tables keep their header row, and quotes become quote blocks.

How to use it

1. Choose your .docx file, or drag it onto the box above.
2. Wait a moment. Larger documents with images take a few seconds.
3. Press Copy.
4. In WordPress, open a new post. Click the options menu at the top right and choose Code editor.
5. Paste, then switch back to the visual editor.

Your content is now made of real blocks. You can drag them, change heading levels, and use block settings the same as anything you typed by hand.

Why Word documents import badly

A .docx file is a zip archive holding XML. That XML describes both what your text says and how Word drew it on screen, and the two are mixed together. Font sizes, spacing, colours and list numbering all live alongside the actual structure.

When something converts that to HTML naively, all of it comes across. You end up with inline styles fighting your theme, spans wrapped around single words, and headings that are only headings because someone made them bigger.

The important distinction is between formatting and structure. A heading style is structure: Word records that this text is a Heading 2, and that survives conversion. Bold text at 16pt is formatting: it looks like a heading and carries nothing a converter can use. This is the single most common reason an import comes out flat, and it is a problem in the document rather than in the tool doing the importing.

If a heading here came out as a plain paragraph, that is why. Fixing it in Word takes a few seconds: select the text and choose the right heading from the Styles gallery on the Home tab. Our Word heading checker lists every heading in a document and flags the ones that are only bold text.

What this tool does not do

It handles one document and gives you text to paste. That is genuinely all, and for a single article it is often the fastest route. There are four things it cannot do, and they are limits of the browser rather than choices we made:

• Images stay as base64. They appear in the markup as encoded text rather than files. They will display, but they are not in your Media Library, so you cannot reuse them, generate thumbnails, or set alt text from the usual screens. This also makes the markup large. A document with several photographs can produce several megabytes of text.
• No SEO fields. A browser tab has no access to Yoast or Rank Math, so nothing can fill in a meta description or a focus keyphrase.
• No categories, tags, author or post type. Those are WordPress settings, and this tool is not inside WordPress.
• One file at a time. No batches, no folders, no zip archives.

If you are moving one article, none of that matters. If you are moving fifty, all of it does, and the copy and paste step alone becomes the slowest part of the job. That is what the plugin is for: it runs inside WordPress, so it can upload images as real attachments, fill SEO fields, set the post type, and work through a hundred documents in one run.

We would rather say that plainly than pretend a browser tab can do a job it cannot.

Does this match what the plugin produces?

Yes, and we check it rather than assume it. The plugin and this tool use the same mapping from HTML to blocks, and a set of fixtures runs through both to confirm they agree. The one difference is images: the plugin has a Media Library to upload to and this tool does not, so the plugin adds an attachment ID that cannot exist here.

What converts, and what falls back

Most of a normal document maps cleanly onto a block. These are handled directly:

• Headings, levels 1 to 6. Only real heading styles. Bold text stays a paragraph, because that is what it is.
• Paragraphs, keeping bold, italic, strikethrough, superscript and links.
• Lists, ordered and unordered, including nested ones. Word tracks indent levels separately from the list itself, and both are read, so a list three levels deep arrives three levels deep.
• Tables. A row marked as a repeating header row in Word becomes a real table header rather than an ordinary first row.
• Quotes.Word’s Quote, Intense Quote and Block Text styles all become quote blocks.
• Images, with their alt text if the document has any.
• Horizontal rules.

Anything without a block equivalent is kept verbatim in an HTML block. That is lossless and still editable, so nothing is ever silently dropped. If you see an HTML block in the output, that is something unusual in the document rather than a failure.

Things that surprise people

Text boxes and shapes do not come across. Word stores those outside the document body, in a separate drawing layer. Nothing reading the file as a document sees them, so a document whose content lives in text boxes converts to almost nothing. If the result looks empty, that is usually why.

Footnotes and endnotes are not blocks.WordPress has a footnote block, but the mapping between Word’s numbering and the block’s is not reliable enough to do automatically, so footnote text arrives as ordinary content.

Tracked changes are applied, not shown. The converter reads the current state of the document, so unaccepted edits give you the edited version. Comments are ignored.

Fonts and colours are dropped on purpose.This is the one that looks like a bug and is not. Your theme should decide what your site looks like. Carrying Word’s 11 point Calibri into your posts is how imported content ends up looking different from everything else you have published.

If the output is very large

Base64 encoding makes an image roughly a third larger than the file it came from, and that text sits inside your post content rather than in the Media Library. A document with a dozen photographs can produce several megabytes of markup, which is slow to paste and slow to load afterwards.

For a document like that the plugin is the better route rather than a preference. It uploads each image as a real attachment, so your post holds a reference instead of the image itself, and WordPress can generate thumbnails and serve the right size to each visitor.