Simplifying Ghost Blogging with CLI Tools

I enjoy sending messages out into the internet, but writing is hard, blogging feels like a chore, and Ghost’s editor leaves much to be desired. To streamline my process, I created a simple integration between Ghost and the local file system, allowing me to write blogs in Markdown and leverage AI tools like CoPilot.

Functional Requirements

• Edit a Markdown file locally and update it to Ghost CMS as an article.
• Download an existing article from Ghost CMS as a Markdown file for local editing.
• Support only Markdown formatting.
• Update only the article body.

Non-Functional Requirements

• The product is a CLI application.
• Includes safeguards to prevent accidental overwrites.

Data Flow Design

Using the Ghost Admin API for /posts, the tool downloads and updates the JSON structure representing an article. The API includes an updated_at check to avoid conflicts with other writers. The key focus is on the "lexical" field, where the article body resides as a JSON string. The tool extracts Markdown content for local editing and reinserts updated content for upload.

Example JSON structure:

{
  "posts": [
    {
      "lexical": {
        "root": {
          "children": [
            {
              "type": "markdown",
              "markdown": "## the content"
            }
          ]
        }
      },
      "updated_at": "2024-11-27T09:17:17.000Z"
    }
  ]
}

Code Design

The integration is implemented as four CLI commands, bundled under a menu for the kwt tool (which I authored). Full details are available on GitHub. Below is the help output:

NAME:
   kwt ghost - Menus for downloading ghost blog posts to local disk /home/psc/.kwt/kwt-ghost/ghost.yaml

USAGE:
   kwt ghost command [command options] [arguments...]

COMMANDS:
   admin, a     make a generic call to ghost admin
   list, l      list posts
   download, d  download post content
   update, u    update post content
   help, h      Shows a list of commands or help for one command

OPTIONS:
   --help, -h  show help

Usage

1. Install kwt:

   Follow installation instructions on the GitHub homepage.

2. Install the ghost menu:

   kwt i -s https://raw.githubusercontent.com/bettercallshao/kwt-ghost/refs/heads/main/ghost.yaml
   

3. Set up API credentials:
   Generate an API key via the Ghost Admin Console.

   export GHOST_ADMIN_API_KEY="KEY"
   export GHOST_API_URL="https://bettercallshao.com"
   

4. List your articles:

   $ kwt g l
   66b5b3f45a6d3a0001b53800 A Peek into Entrepreneurial Lisbon
   66b5ba185a6d3a0001b53874 Try simulation easily with sand
   66b5b73d5a6d3a0001b53834 Present with narratives
   

5. Download an article to edit by ID:

   $ kwt g d -i 66b5b3f45a6d3a0001b53800
   

6. Edit the downloaded file with AI tools:

   code 66b5b3f45a6d3a0001b53800.md
   

7. Upload the edited article by ID:

   $ kwt g u -i 66b5b3f45a6d3a0001b53800
   

Conclusion

This workflow streamlines blogging with Ghost, combining familiar tools with a lightweight and efficient process. If it proves highly useful, the tool could also be reimagined as a VSCode extension for even greater convenience.