Skip to main content
The /publish-draft command publishes draft articles to WordPress as drafts, automatically populating all SEO metadata fields.

​
Usage

/publish-draft [filename] [--type post|page|custom]
​
filename
string
required
Path to the draft file (in drafts/ or rewrites/)
​
--type
string
default:"post"
Post type: post (blog post), page (WordPress page), or custom post type

​
Examples

/publish-draft drafts/content-marketing-guide-2025-03-04.md

​
Post Types

Standard blog postFeatures:
  • Supports categories and tags
  • Chronological feed
  • Author attribution
  • Published as draft by default
Use for: Blog articles, news, tutorials

​
What It Does

1

Parses Draft File

Extracts all metadata from frontmatter:
  • Meta Title
  • Meta Description
  • Primary Keyword (Target Keyword)
  • Secondary Keywords
  • URL Slug
  • Categories
  • Tags
2

Converts Markdown to HTML

  • Converts markdown formatting to HTML
  • Preserves headings (H1-H6)
  • Maintains links and formatting
  • Converts lists and code blocks
3

Creates WordPress Draft

Posts via REST API:
  • Status: draft (never auto-publishes)
  • Title: H1 from article
  • Content: Full HTML content
  • Slug: From frontmatter
  • Author: Current WordPress user
4

Sets Yoast SEO Fields

Automatically populates:
  • SEO Title (Meta Title)
  • Meta Description
  • Focus Keyphrase (Primary Keyword)
  • Canonical URL (if specified)
5

Assigns Taxonomy

If specified in frontmatter:
  • Categories (creates if don’t exist)
  • Tags (creates if don’t exist)
6

Returns Edit URL

Provides direct link to edit in WordPress admin

​
Metadata Mapping

Draft FieldWordPress Field
H1 TitlePost Title
Body ContentPost Content (HTML)
URL SlugPost Slug

​
Setup Requirements

​
Environment Variables

Add to .env file: 
WORDPRESS_URL=https://yoursite.com
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

​
Getting an Application Password

1

Log into WordPress Admin

Navigate to your WordPress dashboard
2

Go to Your Profile

Users > Your Profile
3

Scroll to Application Passwords

Find “Application Passwords” section at bottom
4

Create New Password

  1. Enter name: “SEO Machine”
  2. Click “Add New Application Password”
  3. Copy the generated password
5

Add to .env

Paste into WORDPRESS_APP_PASSWORD in .env file
Security: Application passwords are different from your WordPress login password. They can be revoked individually without changing your main password.

​
WordPress Plugin

Install the Yoast SEO REST API MU-plugin:
1

Install MU-Plugin

Copy wordpress/seo-machine-yoast-rest.php to:
wp-content/mu-plugins/seo-machine-yoast-rest.php
2

Add Functions Snippet

Add code from wordpress/functions-snippet.php to your theme’s functions.php
3

Verify Installation

The plugin exposes Yoast SEO fields to the REST API
See wordpress/README.md for detailed setup instructions.

​
Adding Categories & Tags

To assign categories or tags, add to draft frontmatter: 
**Category**: Content Marketing
Categories and tags are created automatically if they don’t exist in WordPress.

​
Process

1

Validate File

Command confirms the draft file exists and parses metadata:
✓ Found file: drafts/content-marketing-guide-2025-03-04.md
✓ Parsed metadata
✓ Title: "Content Marketing Guide for B2B SaaS"
✓ Meta Title: "Content Marketing Guide: 15 Strategies | YourBrand"
✓ Target Keyword: "content marketing guide"
2

Publish to WordPress

Runs the WordPress publisher:
python data_sources/modules/wordpress_publisher.py \
  "drafts/content-marketing-guide-2025-03-04.md" \
  --type post
3

Confirm Success

Displays WordPress edit URL:
✓ Published to WordPress (Draft)
✓ Post ID: 1234
✓ Edit URL: https://yoursite.com/wp-admin/post.php?post=1234&action=edit

​
Output

Successful publish returns: 
## Publishing Summary

**Status**: ✓ Success
**Post Type**: post
**WordPress Status**: draft
**Post ID**: 1234
**Title**: Content Marketing Guide for B2B SaaS
**URL Slug**: /blog/content-marketing-guide
**Yoast SEO**: ✓ Configured
**Categories**: Content Marketing, SEO
**Tags**: b2b saas, guide

**Edit URL**: https://yoursite.com/wp-admin/post.php?post=1234&action=edit

**Next Steps**:
1. Review the draft in WordPress admin
2. Upload any images or media
3. Preview the post
4. Publish when ready

​
Troubleshooting

Problem: Environment variables not configuredSolution:
  1. Create .env file in root directory
  2. Add WordPress credentials: 
    WORDPRESS_URL=https://yoursite.com
WORDPRESS_USERNAME=your-username
WORDPRESS_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
  3. Verify .env is in .gitignore
Problem: Authentication failedSolutions:
  • Verify username is correct (not email)
  • Regenerate Application Password
  • Ensure user has permission to create posts
  • Check WordPress URL is correct (no trailing slash)
Problem: Category doesn’t existSolution: Categories are created automatically. If error persists:
  • Check category name for special characters
  • Manually create category in WordPress first
  • Verify REST API is enabled for categories
Problem: Yoast SEO REST API not exposedSolution:
  1. Install MU-plugin: wordpress/seo-machine-yoast-rest.php
  2. Verify Yoast SEO plugin is active
  3. Check functions.php snippet is added
  4. Test REST API endpoint: /wp-json/wp/v2/posts
Problem: Custom post type not registered or REST API not enabledSolution:
  1. Verify custom post type exists in WordPress
  2. Check registration includes 'show_in_rest' => true
  3. Test endpoint: /wp-json/wp/v2/[post-type]

​
Important Notes

Posts are created as DRAFTS, never published automatically. Always review in WordPress before publishing.
Images are NOT uploaded - only text content is transferred. Upload images manually in WordPress after publishing.
Multiple runs create multiple drafts - Running the command twice creates two separate draft posts.

​
WordPress Integration

SEO Machine uses the WordPress REST API with a custom MU-plugin for Yoast SEO integration.

​
Architecture

​
Files

wordpress_publisher.py

Python module that handles REST API callsLocation: data_sources/modules/wordpress_publisher.py

seo-machine-yoast-rest.php

MU-plugin that exposes Yoast SEO fields to REST APILocation: wordpress/seo-machine-yoast-rest.php

functions-snippet.php

Additional theme functions for REST API supportLocation: wordpress/functions-snippet.php

README.md

Detailed WordPress setup instructionsLocation: wordpress/README.md

​
Tips

Test First

Test with a simple article first to verify setup.

Review in WordPress

Always review and preview drafts before publishing live.

Upload Images

Add images manually in WordPress after publishing draft.

Check Yoast

Verify Yoast SEO fields populated correctly in WordPress.

/optimize

Optimize before publishing

/write

Create articles to publish

Build docs developers (and LLMs) love

Get started for freeTalk to us