Subscribe

Publishing Markdown posts to Ghost with the Admin API and Python

I write blog posts as Markdown folders in git. A small python script checks each one, renders the HTML, draws a banner with Pillow and creates a draft in Ghost through the Admin API.

Publishing Markdown posts to Ghost with the Admin API and Python

The Ghost editor is nice to write in. But I don't like my posts living only inside a MySQL database on one server, and I write mostly code heavy posts, which are easier in a text editor anyway. So the posts on this blog start as Markdown files in a git repo, next to the Terraform for the server the blog runs on.

In this blog we will look at how a folder of Markdown becomes a draft in Ghost: the folder layout, the build script, the banner image and the Admin API calls.

One folder per post

I write posts in batches. Each batch is a folder named after the date, like nov16, and each post inside it gets its own folder.

blogs/nov16/
  publishing-markdown-posts-to-ghost-with-the-admin-api-and-python/
    title.txt
    excerpt.txt
    tags.txt
    content.md

The folder name is the title in lowercase with every run of other characters turned into one hyphen. Ghost uses the same thing as the slug, so the folder name ends up in the URL.

title.txt is one line. excerpt.txt is the custom excerpt Ghost shows on the home page and in link previews, and Ghost caps it at 300 characters. tags.txt is comma separated, first tag is always the broad one (Tech for nearly everything here). content.md is the body. It doesn't repeat the title, because Ghost already shows it.

Nothing else is written by hand. The build script generates the rest.

The build script

build.py takes a batch folder and does the same steps for every post in it. It needs two packages.

python3 -m venv .venv
.venv/bin/pip install markdown pillow
.venv/bin/python blogs/tools/build.py blogs/nov16

First it checks the files. The slug check is the one I care about most, since renaming a post folder later would change the URL.

import re

def slugify(text: str) -> str:
    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")

def check(folder, title, excerpt, md):
    problems = []
    if folder.name != slugify(title):
        problems.append(f"folder name should be '{slugify(title)}'")
    if len(excerpt) > 300:
        problems.append(f"excerpt is {len(excerpt)} chars (max 300)")
    if chr(0x2014) in md or chr(0x2013) in md:
        problems.append("contains an em/en dash")
    return problems

The dash one is just a house rule for this blog. If anything fails, the script stops with the folder name and the reason. It doesn't try to fix anything for me.

Markdown to HTML

The Markdown library with two extensions is all it takes. fenced_code handles the triple backtick blocks with a language, and tables is for the odd comparison table.

import markdown

html = markdown.markdown(md, extensions=["fenced_code", "tables"])

A fenced block with bash on it comes out as <pre><code class="language-bash">, which is the class name Ghost themes and Prism look for. So syntax highlighting works without anything extra.

Checking the reading time

Ghost shows "X min read" on every post. I wanted to know that number before publishing, and I wanted the script to refuse posts that are too thin. Ghost counts words in the rendered text at 275 words a minute and adds about 12 seconds for the feature image.

import html as html_lib
import re

def ghost_words(html: str) -> int:
    text = html_lib.unescape(re.sub(r"<[^>]+>", " ", html))
    return len(re.findall(r"[a-zA-Z0-9_]+", text))

def reading_time(html: str) -> tuple[float, int]:
    seconds = ghost_words(html) / 275 * 60 + 12
    prose = ghost_words(re.sub(r"<pre>.*?</pre>", "", html, flags=re.S))
    return seconds / 60, prose

The second number is the prose words, everything outside code blocks. A post that is one paragraph and a 200 line script would pass on reading time alone, so the script also wants 700 words of actual writing. The limit is 3.0 minutes before rounding. Ghost would round 2.5 up to 3, and I don't want that.

When a post passes it prints a line like this.

running-ghost-6-and-mysql-8-on-a-2-gb-t3-small: 4.65 min read (Ghost shows 5), 1008 prose words, 4 tags

Drawing the banner

Every post needs a feature image and I didn't want stock photos or anything downloaded. Pillow draws a 1600x900 banner from the post itself: a dark gradient, the tags, the title, and a little terminal window with the first lines of code from content.md.

Here is a cut down version that runs on its own. The fonts are the ones that ship with macOS, change the paths on Linux.

import textwrap
from PIL import Image, ImageDraw, ImageFont

def banner(title: str, code: list[str], out: str) -> None:
    w, h = 1600, 900
    img = Image.new("RGB", (w, h), "#0f172a")
    d = ImageDraw.Draw(img)
    for y in range(h):
        t = y / h
        d.line([(0, y), (w, y)], fill=(int(15 + 10 * t), int(23 + 18 * t), int(42 + 22 * t)))

    d.rounded_rectangle([930, 150, 1530, 670], radius=18, fill="#020617", outline="#334155", width=2)
    mono = ImageFont.truetype("/System/Library/Fonts/Menlo.ttc", 22)
    for i, line in enumerate(code[:11]):
        d.text((958, 220 + i * 38), line[:42], font=mono, fill="#7dd3fc")

    bold = ImageFont.truetype("/System/Library/Fonts/Supplemental/Arial Bold.ttf", 72)
    y = 220
    for line in textwrap.wrap(title, width=19):
        d.text((90, y), line, font=bold, fill="#f8fafc")
        y += 88
    img.save(out, optimize=True)

banner("Publishing Markdown posts to Ghost", ["python3 build.py blogs/nov16"], "banner.png")

The real script shrinks the title font until it fits in five lines, and cuts long code lines to fit the panel instead of wrapping them. Comment lines are skipped when it picks the code. A banner that starts with a comment line just looks empty.

The post payload

The last thing build.py writes is post.json, which is the exact body for the Admin API.

{
  "posts": [
    {
      "title": "Publishing Markdown posts to Ghost with the Admin API and Python",
      "slug": "publishing-markdown-posts-to-ghost-with-the-admin-api-and-python",
      "custom_excerpt": "I write blog posts as Markdown folders in git.",
      "html": "<p>The Ghost editor is nice to write in.</p>",
      "tags": [{"name": "Tech"}, {"name": "Ghost"}],
      "status": "draft",
      "feature_image": null,
      "feature_image_alt": "Publishing Markdown posts to Ghost with the Admin API and Python"
    }
  ]
}

Status is always draft. Nothing goes live without me reading it in Ghost first. Tags are by name, Ghost creates any that don't exist yet.

Talking to the Admin API

In Ghost Admin, under Settings, Integrations, add a custom integration. It gives you an Admin API key that looks like id:secret. The secret is hex. Keep it out of git and out of your shell history. The script below reads it from an environment variable.

The Admin API doesn't take the key directly. You sign a short lived JWT with it: HS256, the id as kid in the header, audience /admin/, and an expiry of at most five minutes. PyJWT can do this, but it's a few lines with the standard library, and I like seeing what goes into it.

import base64, hashlib, hmac, json, time

def b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()

def admin_token(key: str) -> str:
    kid, secret = key.split(":")
    header = {"alg": "HS256", "typ": "JWT", "kid": kid}
    now = int(time.time())
    payload = {"iat": now, "exp": now + 5 * 60, "aud": "/admin/"}
    signing_input = ".".join(
        b64url(json.dumps(part, separators=(",", ":")).encode())
        for part in (header, payload)
    )
    sig = hmac.new(bytes.fromhex(secret), signing_input.encode(), hashlib.sha256).digest()
    return signing_input + "." + b64url(sig)

The bytes.fromhex(secret) is the part that is easy to get wrong. If you sign with the hex string as plain text, the token looks fine but Ghost rejects it.

Uploading the image and creating the draft

This goes in the same file as admin_token. Two requests. Upload the banner, take the URL it returns, put it into post.json, then create the post with ?source=html so Ghost converts the HTML into its own editor format.

import json, os, sys
from pathlib import Path
import requests

api = os.environ.get("GHOST_URL", "https://fenixara.com") + "/ghost/api/admin"
headers = {"Authorization": f"Ghost {admin_token(os.environ['GHOST_ADMIN_KEY'])}"}
folder = Path(sys.argv[1])

with open(folder / "feature-image.png", "rb") as f:
    r = requests.post(f"{api}/images/upload/", headers=headers,
                      files={"file": ("feature-image.png", f, "image/png")},
                      data={"purpose": "image"})
r.raise_for_status()
image_url = r.json()["images"][0]["url"]

post = json.loads((folder / "post.json").read_text())
post["posts"][0]["feature_image"] = image_url
r = requests.post(f"{api}/posts/?source=html", headers=headers, json=post)
r.raise_for_status()
created = r.json()["posts"][0]
print(created["id"], created["status"], created["slug"])

Without ?source=html Ghost ignores the html field and you get a draft with a title and nothing else. That one is worth remembering.

A token is only good for five minutes, so the script makes a fresh one each run. For a whole batch, either loop inside one run or make a new token per post.

Reviewing the draft

Ghost turns each fenced block into a code card and keeps the language class. I still open every draft in Ghost Admin before publishing. Code blocks, the excerpt, the tags and the banner are the four things I check. If something needs a fix I change content.md, build again, and recreate the draft, so the files in git stay the real copy of the post.