Moving an existing Markdown article into WordPress can mean three different things: importing a .md file, writing Markdown in a supported WordPress editor, or converting it to HTML before adding it to a post. Choose based on your source and the kind of WordPress content you need. Then test a small sample in a draft and compare the result with the source before moving the full article.
The important distinction is that a downloadable Markdown file is not the same deliverable as an editable WordPress post. And rendered content is not automatically the same thing as native WordPress blocks. A conversion route may produce a Markdown block, HTML, or other editor content, depending on the tool and setup.
Choose how your Markdown should become a WordPress post
Start with the result you want. If the article should be edited and published as a post, use a route that puts its content into the WordPress editor. If visitors should receive the original .md file, make that a separate file-download task. Uploading or linking to the file alone does not turn its contents into an editable post.
| Starting point | Desired result | Suitable route | Limitation to plan for |
|---|---|---|---|
An existing .md file | An editable post created from the file | Use an importer that supports Markdown files and your WordPress setup | Importing may require a particular plugin or configuration. Check what content it creates and whether it updates an existing post or creates another one. |
| Markdown text you want to keep writing | A post composed in WordPress | Use a Markdown block or editor that is available in your setup | Markdown support is not available in the same way on every WordPress installation. The result may remain a Markdown block rather than becoming individual native blocks. |
| Markdown text that you can convert outside WordPress | Content to add to a post | Convert the Markdown to HTML, then place the HTML in an appropriate WordPress HTML context | HTML can render without becoming native blocks. Raw Markdown pasted into ordinary text content is not a universal conversion method. |
An .md file intended for readers to download | The original file as an attachment or link | Upload or link to the file using your usual media workflow | This offers a file, not an article body that readers can edit in WordPress. |
These are different jobs, even when they start with the same source. A WordPress.com support page documents a Markdown block for composing posts and comments, but its availability and use depend on the WordPress environment. For file import, a plugin’s product page may describe specific import and conversion functions; that does not mean every WordPress site includes them by default. For example, the Ultimate Markdown product page describes bulk Markdown-file import and conversion to blocks. Treat that as a product-specific capability to verify for your site, not as a general WordPress feature.
If you convert to HTML first, the output is markup that describes page structure. It may display as headings, lists and paragraphs, but that appearance alone does not tell you whether the editor stores it as native blocks, one HTML block, or another representation. Decide whether that distinction matters for your editing workflow before choosing the route.
Prepare a small Markdown sample before moving the full article
A short test is safer and more revealing than moving a whole article and discovering that a nested list or image reference behaves differently than expected. The sample below is illustrative. It is not a report of a test in any particular plugin, WordPress site or converter. Copy it into a test draft using the route you are considering, then use the checklist in the next section to assess the result.
## A simple packing list
Bring **one light jacket** for cool evenings. See the [weather guide](https://example.com/weather) before you leave.
Pack in this order:
1. Before you go
- Check the forecast.
- Save the address.
2. On the day
- Carry water.
> Keep essentials where you can reach them.
```text
Departure time: 9:30 AM
Bag size: 20 L
| Item | Ready? |
|---|---|
| Jacket | Yes |
| Water | No |
The sample includes an H2 heading, bold emphasis, a link, a nested list, a blockquote, an image reference, a fenced code block and an optional table. That is enough variety to expose common differences without making you validate a full article.
The image path `images/day-bag.jpg` is deliberately a local-style reference. It only points to a file if the selected process can find that file in the expected location. A web-accessible image URL is different: it identifies an image that can be requested over the web. Neither kind of Markdown reference guarantees that an importer will upload the image into WordPress media. If the image matters, confirm how your route handles the source file, the final image URL and any required media-library step.
The table is optional because Markdown flavours and converters can support different extensions. If tables are important in your real articles, leave it in the test. If not, remove it and focus on the elements your content actually uses. Keep a clean copy of the original sample so you can repeat the same test after changing a route or setting.
## Use the route that matches your source and WordPress setup
For each route, the basic sequence is input, conversion or entry, destination, and first check. You do not need to learn a long list of Markdown editors to make this choice. You need to know what your setup accepts and inspect what it creates.
**Import an existing file.** The input is the `.md` file. First confirm that an importer is available for your WordPress setup and that its documented function covers Markdown files. Test with a copy of the sample or a disposable draft, not the only version of a live article. Run the import using the supported process, then find the resulting draft in WordPress. Your first check is whether the text and structure appeared in the intended destination and whether the importer created the kind of editor content you expect. Before using it on published content, find out whether repeating the import updates an existing post or creates another one.
An importer is the most direct route when you already have a file and want to bring its contents into WordPress. It is not the same as attaching the file to a post. Nor should you assume that the word import means every item in the file becomes a native block. Check the importer’s stated output and confirm the actual result in your draft.
**Write or enter Markdown in WordPress.** The input is Markdown text. Use a Markdown block or editor only if that feature is available in your particular WordPress setup. WordPress.com’s support documentation describes using a Markdown block to compose content with links, lists and other styles. Check the feature in the site where you will publish rather than assuming that support applies identically to every WordPress installation or editor configuration. Enter the short sample, save it as a draft, and check both its editor representation and its rendered preview. If the article already exists as a file, this route means bringing its text into the supported editor; it is not automatically a file-import workflow.
**Convert Markdown to HTML before adding it.** The input is Markdown text or file content; the intermediate result is HTML. Use a converter that supports the syntax your article uses, then place the generated HTML in a WordPress context intended for HTML. A Markdown-to-HTML converter is one way to make that intermediate output; for example, DocsWrite provides a Markdown-to-HTML tool. The expected destination is a post draft containing the converted content. Your first check is whether the HTML displays the intended structure in the editor or preview and whether it remains editable in the way you need.
Do not assume that pasting raw Markdown into an ordinary paragraph or text area will convert it. If you see the asterisks, hash marks or brackets from the source, the destination may be treating your input as plain text rather than parsing Markdown. Also do not assume that HTML which looks correct in preview has become a collection of native blocks. Inspect the editor’s representation if later block-by-block editing matters.
A useful way to choose is to ask two questions: **Where is the source now?** and **What kind of content must the editor maintain afterward?** A finished file points toward a supported import or a conversion step. Ongoing Markdown writing points toward a supported Markdown editor. A need for native blocks, rather than merely rendered content, adds a separate requirement to check the route’s output.
## Compare the WordPress draft with the Markdown source
A conversion passes when the WordPress draft communicates the same content and its important structure and destinations remain correct. Do not judge only by whether the preview looks broadly similar. Compare the source with the editor and, where useful, the rendered preview. The editor shows how content is represented; the preview helps you see what readers may encounter. One view does not answer every question.
Use the sample’s elements as specific pass/fail checks:
| Sample element | Pass condition | If it fails, inspect |
| --- | --- | --- |
| `## A simple packing list` | It is presented as a section heading at the intended level, not merely as a paragraph containing hash marks or bold text | Whether the route parses Markdown headings and whether the editor represents the result as a heading, Markdown block or HTML |
| Bold phrase and link | The emphasis is visible, and the link opens the intended destination | The rendered formatting and the actual link target; do not judge the link by its underlined appearance alone |
| Numbered list with nested bullets | The two sub-items remain visibly nested under the first numbered item | Whether the list hierarchy is still present in the editor and preview, not just whether all words survived |
| Blockquote | The quoted sentence is distinct from the surrounding paragraph | Whether the source syntax was parsed and whether the editor retains the quote structure |
| Image reference | The intended image loads in the intended position | Whether the file or URL is reachable, whether the converter handles image references and whether the image needs separate uploading |
| Fenced code block | The two lines and their punctuation remain intact and visibly set apart as code | Whether the fence was recognized and whether spacing, characters or line breaks changed |
| Optional table | Rows and columns remain aligned, with the correct cell contents | Whether the route supports the table syntax or extension used by the source |
For the link check, open or inspect the destination, not just the visible anchor text. For the image, confirm the actual asset and its placement; a blank image area can indicate a missing file, inaccessible URL or a route that did not transfer the image. For code, compare characters and line breaks directly. A missing backtick may matter if the code itself is the content, and a line break can change how an example is read.
Then identify what WordPress created. Is the content in a Markdown block, in separate blocks, or in an HTML context? The answer can affect how easily you can edit individual parts later. Do not infer it from the preview. Also check the post title field, the post’s draft or other intended status, and the preview for the correct page. Keep the post unpublished while correcting a test conversion.
If you need a simple record, note the route used, the sample’s pass/fail result for each element, and the editor representation. For example: `HTML conversion — heading, link and nested list passed; image needs a separate media step; table not supported; content remains in HTML context.` That gives you a concrete basis for deciding whether to use the route on a longer article, rather than relying on a vague impression that formatting was preserved.
## Fix common conversion problems before publishing
A symptom points to something to investigate; it does not always identify the cause. Check the source and the route, make one correction at a time, then run the same small sample again. That makes it easier to tell whether a change helped.
| Symptom in the draft | What to inspect | Recovery and expected result |
| --- | --- | --- |
| Raw `#`, `**` or link brackets appear | Whether the destination parses Markdown, and whether the content was entered in a supported Markdown editor or block | Use the supported Markdown route, or convert the source before adding it. The test heading and emphasis should render as structure and formatting instead of literal syntax. |
| Image is missing or shows as a broken reference | Whether the path points to a file available to the converter, whether a URL is reachable, and whether the workflow requires a separate media upload | Correct the reference or provide the image through the route’s supported media process. Confirm the image loads in the draft preview at the intended location. |
| Table becomes plain text or loses its columns | Whether the chosen Markdown flavour or converter supports the table syntax used | Use a route that supports the needed table syntax, or rebuild the table in WordPress. Recheck the header and each row rather than assuming alignment from the source text. |
| Code formatting is lost or characters differ | Whether the fenced block was recognized, and whether the source and output contain the same characters and line breaks | Adjust the route or rebuild the code block in the editor. Compare the two lines character by character and confirm they remain set apart from normal prose. |
| Nested bullets become one flat list | Whether the route recognizes indentation and preserves list nesting | Correct the indentation in the source or repair the list in the editor, then confirm the sub-items sit under the intended parent item. |
| Content looks right but is hard to edit in the expected way | Whether the result is a Markdown block, HTML, or individual WordPress blocks | Decide whether the current representation fits future edits. If not, test a route that creates the representation you need and compare its output before moving the full article. |
If a route continues to fail a required check, do not make repeated adjustments to the full article. Return to the small sample and test another supported route or setting. Once the sample passes the checks that matter for your article, move the full source and repeat the comparison on the resulting draft. A complex article may contain elements the sample does not cover, such as additional table types or multiple images, so add those elements to the test when they are important to the real content.
## Keep a clear source of truth for later edits
After publishing, record the Markdown filename or source location and the destination post URL. Decide which copy is authoritative for future changes. If Markdown remains the master, make substantive edits there first and then use a documented process to update WordPress. If WordPress becomes the working master, record that decision and keep an archived source or change note if you still need the original.
Do not edit both copies independently and expect them to stay aligned. A sentence changed in the WordPress post will not necessarily flow back into the `.md` file, and a later import will not necessarily update the existing post. Those behaviors depend on the route; do not assume two-way synchronization. Before repeating an import on a published article, check whether the importer updates, duplicates or otherwise handles an existing post. Test that behavior with a disposable draft when possible.
A small record can include:
- The source filename or location.
- The WordPress post URL or draft reference.
- The chosen source of truth for later edits.
- The route used and any image or table exceptions.
- Whether repeat import behavior has been checked.
If your source is a Word document rather than Markdown, the steps differ; see [Word to WordPress: Transfer a Document and Check the Draft](https://wp001.tenwrite.com/word-to-wordpress-transfer-a-document-and-check-the-draft/). For Markdown, begin with the sample, choose a route your WordPress setup supports, and inspect the draft before transferring the complete article. That small test tells you whether the route handles the structure your content actually needs.