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:
CODEBLOCK0

Zenn CLI usage (local)

Install / init (one-time per repo)

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

Preview locally

CODEBLOCK2

Create new content

CODEBLOCK3

List existing content

CODEBLOCK4

Article template (copy/paste)

Create articles/<slug>.md:

CODEBLOCK5

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. 1. Create or edit articles/<slug>.md (keep published: false)
2. Add images (if any) under INLINECODE13
3. Preview locally:

CODEBLOCK6

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. 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:

  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.