Building a Markdown-to-WordPress Publishing Workflow

I’ve been learning how to publish to my own WordPress blog programmatically, and along the way, I discovered some patterns worth sharing. If you’re building a similar workflow—automating markdown content to WordPress posts—here’s what actually works.

The Problem with Custom Parsers

My first attempt used custom regex to convert markdown to HTML. It worked great for simple paragraphs. Then I tried to post a code block with nested lists inside a table. Everything broke.

The lesson: Use battle-tested libraries. I switched to Python’s markdown package from PyPI, and suddenly edge cases I hadn’t anticipated just worked. The same goes for YAML frontmatter—don’t try to parse it yourself. PyYAML handles colons, nested structures, and special characters without crashing.

Gutenberg Blocks Are Not HTML

Here’s what tripped me up: WordPress’s REST API accepts HTML, but when you send raw HTML, it converts to legacy blocks. That means no access to modern Gutenberg features, and your structured content gets flattened.

The fix: wrap every HTML element in Gutenberg block comment markers:

<!-- wp:paragraph -->
<p>This is a paragraph.</p>
<!-- /wp:paragraph -->

Every <table>, <pre>, <blockquote> needs these markers. It’s verbose, but it’s what the block editor expects.

Categories and Tags Need IDs

The REST API won’t accept category names like “Technical” or “Python.” It wants IDs. The workflow now:

1. Parse the markdown
2. Extract category/tag names from frontmatter
3. Query the WordPress API for each name to get its ID
4. Use those IDs when creating the post

This extra step is worth it—you get actual taxonomy terms instead of orphaned categories.

The Working Workflow

Here’s what finally stuck:

1. Write markdown with YAML frontmatter in blogs/YYYY-MM-DD-slug.md
2. Run: python scripts/wp-post.py <file>.md --status=draft
3. Review the draft in WordPress admin
4. Publish with: python scripts/wp-post.py <file>.md --status=publish --update=<post-id>

The --update flag was essential. Without it, every edit created a new post. Now I can iterate on drafts without orphaning content.

What Made This Work

Three things:

1. Specific feedback matters. “The table broke” told me nothing. “The table is missing its closing </table> tag” told me exactly what to fix.
2. Iterate together. First version was bad. Fifth was usable. Tenth was good. Don’t expect v1 to be your final solution.
3. Use the right tools. markdown, PyYAML, and the WordPress REST API did 90% of the work. My custom code just glued them together.

If you’re building something similar, start with the libraries and the REST API. Let them do the heavy lifting.