Zenn: GitHub Push/PR Publishing

Overview

Zenn publishes by syncing a GitHub repository. Articles/books are Markdown files placed in specific directories, and Zenn CLI helps you preview and scaffold content locally.

This skill defines an operational workflow that is both fast and safe: - Draft in PRs (published: false) - Review with local preview (zenn preview) - Publish by flipping published: true once the PR is ready

Inputs to collect

• Repo path (local clone) and GitHub remote
• Publishing branch (the branch connected to Zenn)
• Article metadata: title, emoji, type (tech or idea), topics, published
• Slug / filename for the Markdown file (kebab-case recommended)
• Assets (images) location strategy (recommended: images/<slug>/...)

File placement rules (Zenn)

• Articles must be placed under articles/ as individual .md files.
• (Optional) Books are placed under books/.

Recommended repo layout:

.
├─ articles/
│  └─ 20260216-openclaw-to-zenn.md
├─ books/                # optional
└─ images/               # optional, recommended
   └─ openclaw-to-zenn/
      ├─ cover.png
      └─ diagram.png

Zenn CLI usage (local)

Install / init (one-time per repo)

If Zenn CLI is not set up yet in the repo:

npm init --yes
npm install zenn-cli
npx zenn init

Preview locally

npx zenn preview

Create new content

npx zenn new:article
npx zenn new:book

List existing content

npx zenn list:articles
npx zenn list:books

Article template (copy/paste)

Create articles/<slug>.md:

---
title: "記事タイトル"
emoji: "🧩"
type: "tech" # tech or idea
topics: ["ruby", "rails", "ai"]
published: false
---

## TL;DR
- ...
- ...
- ...

## 背景
...

## 実装 / 検証
...

## 学び
...

## 参考
- ...

Notes: - Title is in front matter, so body headings should generally start at ##. - Keep topics to a small, consistent set for series-building.

Standard workflow (recommended)

1) Draft in a feature branch

1. Create or edit articles/<slug>.md (keep published: false)
2. Add images (if any) under images/<slug>/...
3. Preview locally: bash npx zenn preview

2) Open a PR

git checkout -b article/<slug>
git add articles/<slug>.md images/<slug>/
git commit -m "Add draft: <title>"
git push -u origin article/<slug>

Open a PR into the Zenn publishing branch.

3) Publish safely

Option A (safest): publish in a second tiny PR/commit 1. Merge the draft PR (still published: false) 2. Flip to published: true and merge a small PR

Option B (fast): publish in the same PR - Keep published: false during writing/review - Flip to true right before merging

Quality gate checklist (minimum)

Before setting published: true, verify: - No confidential info (customer names, internal URLs, unreleased metrics) - Code blocks are runnable or clearly labeled as pseudo-code - Images render and paths are correct - Links are correct - Spelling / headings / formatting are acceptable

Troubleshooting

• Preview differs from Zenn web or CLI shows update notice: bash npm install zenn-cli@latest
• Images not showing:
• Ensure they are committed and pushed
• Ensure references look like /images/<slug>/... (not ./images/...)
• Article not appearing:
• File is under articles/
• published: true
• The branch synced to Zenn is the one being updated

When does this not work?

• Skipping PR review (direct publish) increases risk of accidental leaks.
• Relying on UI/browser automation instead of GitHub sync is brittle to UI changes.
• Mixing multiple articles in one file or placing files outside articles/ will not publish as expected.