I got tired of the same three-step content publish loop: write draft → open CMS → paste, format, re-paste, fight the rich-text editor, click publish. Repeat for every environment — staging, then production. For one article, fine. For a team publishing 20+ pieces a month? That workflow is a quiet tax on everyone's time.
So I wired up a pipeline that cuts the loop entirely. You commit a .md file to a Git repo. A GitHub Actions workflow runs. The article is live on WordPress, Ghost, or Webflow — formatted, tagged, and published — within 90 seconds of the push.
Here's the complete workflow, every config file, and the two places where this will bite you if you're not careful.
What You'll Actually Build
By the end of this, you'll have:
- A GitHub repo that acts as your content source of truth
- A GitHub Actions workflow that triggers on push to
main - A Node.js publish script that parses frontmatter, transforms Markdown, and hits your CMS API
- Support for WordPress (REST API), Ghost (Admin API), and Webflow (CMS API) — pick one or all three
- A staging branch that publishes drafts, a
mainbranch that publishes live
Here's the directory structure we're building toward:
content-pipeline/
├── .github/
│ └── workflows/
│ └── publish.yml
├── posts/
│ ├── my-first-post.md
│ └── another-post.md
├── scripts/
│ ├── publish.js
│ ├── publishers/
│ │ ├── wordpress.js
│ │ ├── ghost.js
│ │ └── webflow.js
│ └── utils/
│ ├── parse-frontmatter.js
│ └── transform-markdown.js
├── package.json
└── .env.example
Why This Is Harder Than It Looks
The obvious approach — "just hit the API with the Markdown" — doesn't work in practice. Three reasons:
1. CMS APIs don't accept raw Markdown. WordPress wants HTML. Ghost accepts Markdown but has its own Lexical editor format for complex content. Webflow expects structured JSON with rich text field schemas.
2. Frontmatter is your metadata contract, and every CMS maps it differently. tags in Ghost is an array of tag objects. In WordPress, it's an array of tag IDs you have to look up first. In Webflow, tags don't exist — you have custom field slugs.
3. Idempotency. If the Action runs twice, you don't want two copies of the same article. You need a slug-based lookup before every publish to decide "create" vs "update."
These aren't edge cases — they'll hit you on the first real push. The script below handles all three.
Prerequisites
- Node.js 18+
- A GitHub repo (free tier works)
- At least one of: a WordPress site with Application Passwords enabled, a Ghost instance with Admin API access, a Webflow CMS collection
- Basic familiarity with GitHub Actions syntax
Step 1: The Frontmatter Contract
Every post needs a consistent frontmatter block. This is how the publish script knows what to do with each file.
---
title: "My Article Title"
slug: "my-article-title"
description: "One-sentence summary for meta descriptions and CMS excerpts."
tags: ["javascript", "devops", "tutorial"]
status: "published" # or "draft"
targets: ["wordpress", "ghost"] # which CMSes to publish to
date: "2025-01-15"
cover_image: "https://images.unsplash.com/photo-xyz"
---
Your article content starts here...
The targets field is the key one. It lets a single repo serve multiple CMSes without every post going everywhere. A marketing post might target WordPress only. A technical deep-dive might go to Ghost. The script reads this and routes accordingly.
Step 2: The Frontmatter Parser
// scripts/utils/parse-frontmatter.js
import fs from 'fs';
import matter from 'gray-matter';
import { marked } from 'marked';
export function parsePost(filePath) {
const raw = fs.readFileSync(filePath, 'utf-8');
const { data: frontmatter, content } = matter(raw);
// Validate required fields before we touch any API
const required = ['title', 'slug', 'targets'];
const missing = required.filter(field => !frontmatter[field]);
if (missing.length > 0) {
throw new Error(`Missing required frontmatter fields: ${missing.join(', ')} in ${filePath}`);
}
return {
frontmatter,
markdown: content,
html: marked(content), // WordPress needs this
filePath,
};
}
Two things worth calling out here: gray-matter is the standard Markdown frontmatter parser — rock solid, widely used. And I'm converting to HTML at parse time so every publisher gets both formats and can choose what it needs. You'll need to install these:
npm install gray-matter marked
Step 3: The WordPress Publisher
WordPress's REST API is the most mature of the three. The catch is tag handling — you can't just pass tag names; you have to resolve them to IDs first, creating any that don't exist.
// scripts/publishers/wordpress.js
const WP_BASE = process.env.WP_BASE_URL; // e.g. https://yourblog.com
const WP_USER = process.env.WP_USERNAME;
const WP_PASS = process.env.WP_APP_PASSWORD; // Application Password, not your login password
const authHeader = 'Basic ' + Buffer.from(`${WP_USER}:${WP_PASS}`).toString('base64');
async function resolveTagIds(tagNames) {
const ids = [];
for (const name of tagNames) {
// Check if tag exists
const searchRes = await fetch(
`${WP_BASE}/wp-json/wp/v2/tags?search=${encodeURIComponent(name)}`,
{ headers: { Authorization: authHeader } }
);
const existing = await searchRes.json();
if (existing.length > 0) {
ids.push(existing[0].id);
} else {
// Create it
const createRes = await fetch(`${WP_BASE}/wp-json/wp/v2/tags`, {
method: 'POST',
headers: {
Authorization: authHeader,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name }),
});
const newTag = await createRes.json();
ids.push(newTag.id);
}
}
return ids;
}
export async function publishToWordPress({ frontmatter, html }) {
const tagIds = await resolveTagIds(frontmatter.tags ?? []);
// Check if post already exists (idempotency)
const slugCheckRes = await fetch(
`${WP_BASE}/wp-json/wp/v2/posts?slug=${frontmatter.slug}`,
{ headers: { Authorization: authHeader } }
);
const existing = await slugCheckRes.json();
const payload = {
title: frontmatter.title,
slug: frontmatter.slug,
content: html,
excerpt: frontmatter.description ?? '',
status: frontmatter.status ?? 'draft',
tags: tagIds,
date: frontmatter.date,
featured_media: 0, // Extend this if you want cover image upload
};
if (existing.length > 0) {
// Update
const res = await fetch(`${WP_BASE}/wp-json/wp/v2/posts/${existing[0].id}`, {
method: 'PUT',
headers: { Authorization: authHeader, 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
const updated = await res.json();
console.log(`✅ WordPress: Updated "${updated.title.rendered}" → ${updated.link}`);
return updated;
} else {
// Create
const res = await fetch(`${WP_BASE}/wp-json/wp/v2/posts`, {
method: 'POST',
headers: { Authorization: authHeader, 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
const created = await res.json();
console.log(`✅ WordPress: Created "${created.title.rendered}" → ${created.link}`);
return created;
}
}
Important: Use WordPress Application Passwords, not your account password. Go to Users → Profile → Application Passwords in your WP Admin. The format is username:xxxx xxxx xxxx xxxx xxxx xxxx (with spaces — that's normal).
Step 4: The Ghost Publisher
Ghost's Admin API uses JWT authentication, which is slightly more involved to set up but more elegant once it's running. Ghost also accepts Markdown natively via its mobiledoc format, but the cleanest approach for programmatic publishing is using the @tryghost/admin-api package.
npm install @tryghost/admin-api
// scripts/publishers/ghost.js
import GhostAdminAPI from '@tryghost/admin-api';
const ghost = new GhostAdminAPI({
url: process.env.GHOST_URL, // e.g. https://yoursite.ghost.io
key: process.env.GHOST_ADMIN_KEY, // Format: id:secret (from Ghost Admin → Integrations)
version: 'v5.0',
});
export async function publishToGhost({ frontmatter, markdown }) {
// Ghost tags are objects, not just strings
const tags = (frontmatter.tags ?? []).map(name => ({ name }));
const postData = {
title: frontmatter.title,
slug: frontmatter.slug,
mobiledoc: buildMobiledoc(markdown),
custom_excerpt: frontmatter.description ?? '',
status: frontmatter.status ?? 'draft',
tags,
published_at: frontmatter.date ? new Date(frontmatter.date).toISOString() : undefined,
feature_image: frontmatter.cover_image ?? null,
};
try {
// Try to find existing post by slug
const existing = await ghost.posts.browse({ filter: `slug:${frontmatter.slug}` });
if (existing.length > 0) {
const updated = await ghost.posts.edit({
id: existing[0].id,
updated_at: existing[0].updated_at, // Required for conflict detection
...postData,
});
console.log(`✅ Ghost: Updated "${updated.title}" → ${updated.url}`);
return updated;
} else {
const created = await ghost.posts.add(postData);
console.log(`✅ Ghost: Created "${created.title}" → ${created.url}`);
return created;
}
} catch (err) {
throw new Error(`Ghost publish failed: ${err.message}`);
}
}
// Ghost uses Mobiledoc internally. This wraps raw Markdown in a Markdown card.
function buildMobiledoc(markdown) {
return JSON.stringify({
version: '0.3.1',
markups: [],
atoms: [],
cards: [['markdown', { markdown }]],
sections: [[10, 0]],
});
}
Step 5: The Webflow Publisher
Webflow is the most opinionated of the three. Your CMS collection fields need to match your frontmatter keys, and you'll map them explicitly. This also means the publisher is the most customizable.
// scripts/publishers/webflow.js
const WF_TOKEN = process.env.WEBFLOW_API_TOKEN;
const WF_COLLECTION_ID = process.env.WEBFLOW_COLLECTION_ID;
const headers = {
Authorization: `Bearer ${WF_TOKEN}`,
'Content-Type': 'application/json',
'accept-version': '1.0.0',
};
export async function publishToWebflow({ frontmatter, html }) {
// Check for existing item by slug
const listRes = await fetch(
`https://api.webflow.com/collections/${WF_COLLECTION_ID}/items`,
{ headers }
);
const { items } = await listRes.json();
const existing = items?.find(item => item['slug'] === frontmatter.slug);
// Map your frontmatter to Webflow field slugs
// These must match the field slugs in your Webflow CMS collection
const fields = {
name: frontmatter.title,
slug: frontmatter.slug,
'post-body': html, // Your rich-text field slug in Webflow
'meta-description': frontmatter.description ?? '',
'tags-string': (frontmatter.tags ?? []).join(', '), // Webflow doesn't have native tags
_archived: false,
_draft: frontmatter.status !== 'published',
};
if (existing) {
const updateRes = await fetch(
`https://api.webflow.com/collections/${WF_COLLECTION_ID}/items/${existing._id}`,
{ method: 'PUT', headers, body: JSON.stringify({ fields }) }
);
const updated = await updateRes.json();
console.log(`✅ Webflow: Updated "${updated.fields.name}"`);
// Publish immediately if status is "published"
if (frontmatter.status === 'published') {
await publishWebflowItem(updated._id);
}
return updated;
} else {
const createRes = await fetch(
`https://api.webflow.com/collections/${WF_COLLECTION_ID}/items`,
{ method: 'POST', headers, body: JSON.stringify({ fields }) }
);
const created = await createRes.json();
console.log(`✅ Webflow: Created "${created.fields.name}"`);
if (frontmatter.status === 'published') {
await publishWebflowItem(created._id);
}
return created;
}
}
// Webflow requires a separate "publish" API call after creating/updating
async function publishWebflowItem(itemId) {
await fetch(
`https://api.webflow.com/collections/${WF_COLLECTION_ID}/items/publish`,
{
method: 'PUT',
headers,
body: JSON.stringify({ itemIds: [itemId] }),
}
);
}
Webflow gotcha: The "publish" step is separate from creating/updating. If you skip it, your item will exist in the CMS but won't be live. I missed this for about an hour wondering why my posts weren't showing up.
Step 6: The Main Publish Script
This ties everything together. It finds changed .md files, parses them, and routes to the right publishers.
// scripts/publish.js
import { parsePost } from './utils/parse-frontmatter.js';
import { publishToWordPress } from './publishers/wordpress.js';
import { publishToGhost } from './publishers/ghost.js';
import { publishToWebflow } from './publishers/webflow.js';
import { execSync } from 'child_process';
import path from 'path';
const PUBLISHERS = {
wordpress: publishToWordPress,
ghost: publishToGhost,
webflow: publishToWebflow,
};
async function main() {
// Get list of changed .md files from git
// In GitHub Actions, GITHUB_SHA gives us the current commit
const changedFiles = execSync(
'git diff --name-only HEAD~1 HEAD -- "posts/*.md"'
)
.toString()
.trim()
.split('\n')
.filter(Boolean);
if (changedFiles.length === 0) {
console.log('No markdown files changed. Nothing to publish.');
return;
}
console.log(`Found ${changedFiles.length} changed post(s): ${changedFiles.join(', ')}`);
const results = { success: [], failed: [] };
for (const filePath of changedFiles) {
const fullPath = path.resolve(filePath);
try {
const post = parsePost(fullPath);
const { targets = [] } = post.frontmatter;
if (targets.length === 0) {
console.log(`⚠️ Skipping ${filePath}: no targets specified in frontmatter`);
continue;
}
for (const target of targets) {
const publisher = PUBLISHERS[target];
if (!publisher) {
console.warn(`⚠️ Unknown target "${target}" in ${filePath}`);
continue;
}
await publisher(post);
}
results.success.push(filePath);
} catch (err) {
console.error(`❌ Failed to publish ${filePath}: ${err.message}`);
results.failed.push({ filePath, error: err.message });
}
}
console.log(`\nDone. ${results.success.length} succeeded, ${results.failed.length} failed.`);
// Exit with error if any publish failed — this fails the GitHub Action
if (results.failed.length > 0) {
process.exit(1);
}
}
main();
Step 7: The GitHub Actions Workflow
# .github/workflows/publish.yml
name: Publish Content
on:
push:
branches:
- main # Publishes live
- staging # Publishes as drafts (see note below)
paths:
- 'posts/**' # Only triggers when posts change — not on script edits
jobs:
publish:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 2 # Need at least 2 commits for git diff to work
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run publish script
env:
# WordPress
WP_BASE_URL: ${{ secrets.WP_BASE_URL }}
WP_USERNAME: ${{ secrets.WP_USERNAME }}
WP_APP_PASSWORD: ${{ secrets.WP_APP_PASSWORD }}
# Ghost
GHOST_URL: ${{ secrets.GHOST_URL }}
GHOST_ADMIN_KEY: ${{ secrets.GHOST_ADMIN_KEY }}
# Webflow
WEBFLOW_API_TOKEN: ${{ secrets.WEBFLOW_API_TOKEN }}
WEBFLOW_COLLECTION_ID: ${{ secrets.WEBFLOW_COLLECTION_ID }}
run: node scripts/publish.js
Set all those secrets.* values in your repo under Settings → Secrets and variables → Actions. None of these should ever touch your codebase directly.
The staging branch pattern: Push to staging when the post is a draft you want to preview in the real CMS. The frontmatter's status field controls whether it's a draft or published — so pushing to staging doesn't auto-publish; it just means "run the pipeline." You still control publish state via frontmatter.
What Can Go Wrong
Git diff returns empty on the first commit. The HEAD~1 diff requires at least two commits. If your repo is brand new and this is the first push, there's no HEAD~1. Fix: use git diff --name-only 4b825dc..HEAD -- "posts/*.md" (the magic empty tree SHA) for the initial commit, or add a guard:
const isFirstCommit = execSync('git rev-list --count HEAD').toString().trim() === '1';
const diffCommand = isFirstCommit
? 'git diff --name-only 4b825dc HEAD -- "posts/*.md"'
: 'git diff --name-only HEAD~1 HEAD -- "posts/*.md"';
WordPress Application Passwords with special characters. WP generates passwords with spaces. When you put username:abcd efgh ijkl in an env variable, the spaces can cause header parsing issues. URL-encode the password or store it already base64-encoded.
Ghost updated_at mismatch. Ghost's edit endpoint requires you pass back the updated_at timestamp from the fetched post, or it rejects the update with a 409 conflict. The code above handles this, but if you strip that field for any reason, you'll get confusing errors.
Webflow's API rate limit is 60 requests/minute. If you're bulk-publishing 30+ posts in one commit (like migrating a blog), you'll hit it. Add a delay between requests:
// Add after each publish call inside the loop
await new Promise(resolve => setTimeout(resolve, 1100)); // ~55 req/min
The workflow doesn't trigger when you expect. Double-check your paths filter — posts/** only fires when files inside posts/ change. If you accidentally commit to posts/drafts/ and your pattern doesn't include subdirectories, nothing runs. posts/** handles subdirectories; posts/* does not.
The .env.example File
Commit this to the repo so anyone cloning it knows what to configure:
# WordPress
WP_BASE_URL=https://yourblog.com
WP_USERNAME=your_wp_username
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
# Ghost
GHOST_URL=https://yoursite.ghost.io
GHOST_ADMIN_KEY=id:secret
# Webflow
WEBFLOW_API_TOKEN=your_token
WEBFLOW_COLLECTION_ID=your_collection_id
Never commit a .env with real values. The .gitignore should include .env from the start.
Where to Take This Next
The core pipeline is solid as-is. Three extensions worth building if you use this heavily:
Image optimization on push. Add a step before publish.js that pulls image URLs from Markdown, downloads them, runs them through sharp, and uploads to your CDN. Then rewrites the src attributes before publishing. The article goes live already using your own CDN, not third-party hotlinks.
Slack notification on success/failure. Add a final workflow step that posts to a #content-deploys channel. The message should include the article title, which CMSes it published to, and a link. Tiny addition, huge QoL for a content team.
Scheduled publishing. Frontmatter already has a date field. You can add a GitHub Actions schedule trigger (on: schedule) that runs the publisher daily and checks whether any post's date has passed and its status is scheduled. Publish those automatically. True scheduled publishing without any CMS-specific plan tier.
The full working repo is on GitHub — link in my profile. Drop a star if this saved you the setup time. And if you've wired this up to a different CMS — Contentful, Sanity, Strapi — I'd genuinely like to see how you handled the schema mapping. Drop it in the comments.
Alternative title: "How I Turned My GitHub Repo Into a Headless CMS Publisher (With Working Code)"
Tags: githubactions webdev devops tutorial
Cover image search: "github terminal workflow dark automation deploy"
GitHub repo to create: markdown-cms-publisher — include /posts/example-post.md with sample frontmatter so people can clone and test immediately
Cross-post: Share on r/webdev and r/devops with the title "Built a Markdown → WordPress/Ghost/Webflow publisher using GitHub Actions — complete code inside." Also worth submitting to Hacker News as a Show HN.
This article was originally published by DEV Community and written by Aakash Gour.
Read original article on DEV Community