name	github-hugo-blog-ops
description	Operate a GitHub-hosted Hugo blog repository end-to-end. Use when tasks include creating/editing drafts in content/posts, publishing/unpublishing posts, running quality gates (doctor/seo/media checks), previewing or scheduling content, deploying safely with rollback tags, opening PR-based publish flows, or maintaining theme/workflow infrastructure.

GitHub Hugo Blog Ops

Use this skill to execute repeatable blog workflows safely through scripts/blogctl.sh.

Quick Start

Run commands from repo root.
Use skills/github-hugo-blog-ops/scripts/blogctl.sh.
Export BLOG_ROOT if running the script from outside this repo.

export BLOG_ROOT=/path/to/your/blog-repo
skills/github-hugo-blog-ops/scripts/blogctl.sh list

Workflow Decision

Draft or edit content: Use new, then edit markdown in content/posts/*.md.
Publish content directly on main: Use publish, check, then safe-deploy --push.
Publish via PR: Use pr-flow (recommended when review is required).
Maintain infrastructure: Use bootstrap, maintain, update-theme, and doctor.
QA/SEO/media cleanup: Use doctor, seo, and media.

Create Drafts

Use new to generate a correctly formatted TOML front matter block.

skills/github-hugo-blog-ops/scripts/blogctl.sh new \
  --title "Install FFmpeg on macOS (2026 Update)" \
  --summary "Practical ffmpeg install and verification commands for macOS." \
  --keywords "ffmpeg,macos,video" \
  --pin

Then write or revise the body in the created markdown file under content/posts/.

Publish Posts

Use publish to flip draft to false and set lastmod.

skills/github-hugo-blog-ops/scripts/blogctl.sh publish install-ffmpeg-on-macos
skills/github-hugo-blog-ops/scripts/blogctl.sh check
skills/github-hugo-blog-ops/scripts/blogctl.sh safe-deploy --message "Publish ffmpeg guide updates" --push

Use unpublish to move a live post back to draft mode.

New Operational Commands

bootstrap: Initialize submodules and environment sanity checks.
doctor: Validate front matter, links, markdown quality, and build health.
preview: Run local Hugo preview with drafts/future content support.
schedule list: Show future posts via Hugo listing.
schedule publish-due: Auto-publish due drafts based on date.
media audit: Find empty image alt text and non-kebab local image names.
media normalize: Rename local media filenames to kebab-case and update references.
media compress: Compress large local images (threshold-based).
seo: Audit title/summary lengths, canonical fields, OG cover, sitemap/robots.
safe-deploy: Check + commit + tag + optional push, with rollback support.
pr-flow: Create branch, commit, push, and optionally open GitHub PR.

PR Flow Example

skills/github-hugo-blog-ops/scripts/blogctl.sh doctor
skills/github-hugo-blog-ops/scripts/blogctl.sh pr-flow \
  --branch "post/ffmpeg-2026-update" \
  --message "post: ffmpeg 2026 update" \
  --title "Update ffmpeg install guide" \
  --body "Refresh steps and verification commands."

Use --dry-run first for safe-deploy and pr-flow to preview actions safely.

Maintenance Tasks

Use maintain for repository health signals:

git working tree summary
submodule status for themes/github-style
presence of .github/workflows/hugo.yml
local Hugo installation status

Use update-theme to fast-forward the theme submodule and prepare a commit.

skills/github-hugo-blog-ops/scripts/blogctl.sh bootstrap --update-theme
skills/github-hugo-blog-ops/scripts/blogctl.sh doctor
skills/github-hugo-blog-ops/scripts/blogctl.sh update-theme
skills/github-hugo-blog-ops/scripts/blogctl.sh check
skills/github-hugo-blog-ops/scripts/blogctl.sh safe-deploy --message "Update theme submodule" --push

Guardrails

Avoid manual front matter toggles when blogctl.sh can do it deterministically.
Run doctor and check before safe-deploy --push.
Keep publishing on main because GitHub Pages deployment is triggered by pushes to main.
Prefer pr-flow over direct pushes when review/approval is needed.
Keep commits scoped to blog changes; avoid unrelated edits in publish commits.
Use safe-deploy rollback --dry-run before real rollback.

Reference File

Load references/repository-operations.md for path conventions, deployment mechanics, and maintenance checklist.

name	github-hugo-blog-ops
description	Operate a GitHub-hosted Hugo blog repository end-to-end. Use when tasks include creating/editing drafts in content/posts, publishing/unpublishing posts, running quality gates (doctor/seo/media checks), previewing or scheduling content, deploying safely with rollback tags, opening PR-based publish flows, or maintaining theme/workflow infrastructure.