hexo-blog-publisher

name

hexo-blog-publisher

description

Create, refine, publish, and deploy Hexo blog posts or documentation from any user-provided idea, requirement, note, file, topic, or current Codex/GPT conversation. Use when the user asks Codex to think through an article topic, expand a rough idea into a publishable post, write technical or reflective Hexo content, manage Hexo categories/tags/front matter, insert images automatically, run WSL commands, execute `hexo new`, `hexo clean`, `hexo generate`, `hexo deploy`, or automate a Hexo blog publishing workflow. This skill is Hexo-first today, while its repository may be named `blog-publisher-skill` to leave room for future publishing targets.

Hexo Blog Publisher

Scope

This skill is currently Hexo-first: write Hexo Markdown, manage Hexo front matter and assets, and run Hexo commands through WSL. Keep the workflow modular so future versions can add other publishing targets such as Hugo, Zhihu, Feishu, Yuque, or other knowledge platforms without weakening the current Hexo behavior.

Do not claim support for non-Hexo targets until explicit instructions or resources for those targets are added.

Core Workflow

Use this skill to turn any viable input into a polished Hexo post or document, create it in a Hexo project through WSL, enrich it with categories/tags/images, validate it, and deploy it when the user asks for publishing.

Accept these input modes:

• Conversation mode: distill the current Codex/GPT session into a reader-facing article.
• Idea mode: expand a sudden thought, title, sentence, question, or loose direction into a coherent post.
• Requirement mode: turn a user request, product need, workflow, feature, or problem statement into documentation or an article.
• Source mode: synthesize notes, local files, drafts, screenshots, code changes, or external material provided by the user.

Default to action. Ask clarifying questions only when a missing detail would materially change the post, target repo, or deployment safety.

1. Determine the input mode and publishing intent.
2. Locate the Hexo project. Prefer an explicit user path. Otherwise inspect likely WSL paths with wsl.exe -- bash -lc "pwd; ls; find ..." from the workspace context.
3. Think through the article before writing. Infer the reader, thesis, angle, structure, missing context, useful examples, and likely category/tag set.
4. Expand weak input into a useful outline. If the user gives only a rough idea, produce the best reasonable article direction instead of stopping.
5. Draft the article as a Hexo Markdown post with complete front matter.
6. Inspect existing post filenames and URL fields before creating the post. Match the local convention or the user's explicit filename language. If existing posts use English slugs, use an English slug filename even when the visible title is Chinese.
7. Create the post with Hexo when possible: wsl.exe -- bash -lc "cd '<hexo-root>' && hexo new post '<safe-slug-or-title>'".
8. Rename the generated file when Hexo creates a filename that does not match the local convention. Keep subtitle, slug-like URL fields, and filename aligned when the theme uses them for permalinks.
9. Edit the generated Markdown file. Preserve Hexo front matter and theme conventions.
10. Add images when useful and available. Copy or generate images into the post asset folder or configured image directory, then reference them with stable relative paths.
11. Validate locally with Hexo commands, then deploy only when the user asked to publish or gave clear approval.
12. After a successful publish, automatically git-add, commit, and push the created or updated source Markdown and article images in the Hexo source repository. Stage only the article-related files, not unrelated working tree changes.

Thinking And Expansion

When the user provides a topic, idea, requirement, or fragment, do not treat it as insufficient by default. Turn it into a publishable direction.

Reason in this order:

1. Extract the durable value: what insight, method, story, decision, tutorial, opinion, or reference would help readers later?
2. Choose an article type: tutorial, essay, project log, requirement analysis, tool note, workflow playbook, comparison, checklist, or release note.
3. Define the reader and promise: who benefits, and what can they do or understand after reading?
4. Fill gaps responsibly: add reasonable background, structure, examples, and caveats. Mark uncertain facts as assumptions or avoid them.
5. Avoid making up external facts, version numbers, benchmarks, legal/medical/financial claims, or project details not present in context unless verified.
6. Convert the idea into an outline, then into final Markdown.

Use current conversation content only when it is relevant. A sudden new idea should be developed on its own terms.

Read references/article-guidelines.md when the user asks for a strong article, a series, a specific style, a rough idea expansion, or higher editorial quality.

Conversation Distillation

When the article is based on the current Codex/GPT session, do not transcribe the chat. Convert it into a reader-facing artifact.

Distill in this order:

1. Identify the central transformation: what changed from confusion to clarity, from raw work to useful method, or from scattered notes to reusable insight.
2. Keep only reusable knowledge: decisions, heuristics, pitfalls, examples, code patterns, prompts, design principles, or operational steps.
3. Remove conversational noise: greetings, repeated attempts, tool chatter, partial dead ends, private implementation details, and anything that only made sense inside the chat.
4. Preserve the authentic point of view: what was learned, what tradeoffs mattered, and why the final approach is better for future readers.
5. End with a practical takeaway: checklist, reusable prompt, code snippet, workflow, lesson, or next step.

Hexo Operations

Always run Hexo through WSL when executing commands:

wsl.exe -- bash -lc "cd '<hexo-root>' && hexo new post '<safe-title>'"
wsl.exe -- bash -lc "cd '<hexo-root>' && hexo clean && hexo generate"
wsl.exe -- bash -lc "cd '<hexo-root>' && hexo deploy"

Use single quotes around WSL paths when possible. Escape embedded single quotes in titles or paths.

Before deployment:

1. Check git status in the Hexo repo when it is a git workspace.
2. Run hexo clean && hexo generate.
3. Inspect generation errors, missing asset warnings, invalid front matter, and broken image paths.
4. Deploy with hexo deploy only after validation succeeds and the user intended publishing.
5. After deployment succeeds, commit and push the source article files and images in the Hexo source repo when it is a git workspace.

Read references/hexo-operations.md for command patterns, path discovery, post asset conventions, and deployment safeguards.

Front Matter Rules

Create complete Hexo front matter unless the local theme requires a different schema:

---
title: "Clear reader-facing title"
date: 2026-06-05 15:30:00
categories:
  - "Primary Category"
tags:
  - "tag-one"
  - "tag-two"
description: "One-sentence summary for listings and SEO."
cover: "/path-or-relative-image.jpg"
---

Use the current local timezone when generating dates. Keep category names stable and sparse; use tags for specificity.

Filename and URL slug rules:

• Inspect existing posts first and follow their naming language and date prefix pattern.
• Prefer lowercase ASCII slugs with hyphens when existing posts use English filenames or when the permalink depends on subtitle.
• A Chinese post title may still use an English filename and English subtitle for a stable URL.
• Use user-specified filename language or slug when provided.
• Do not leave Hexo's auto-generated filename in place if it conflicts with the site's established convention.

Category design:

• Use 1 primary category by default.
• Use 2 categories only when the post naturally belongs to a series or discipline plus format.
• Prefer durable buckets such as AI, Engineering, Productivity, Writing, Workflow, Tools, Learning Notes, Projects, Ideas, Docs.

Tag design:

• Use 3-7 tags by default.
• Include concrete technologies (hexo, codex, wsl, prompt-engineering) and concepts (automation, blogging, workflow-design).
• Avoid near-duplicate tags, one-off poetic tags, or tags that merely repeat the category.

Image Handling

Support images automatically when they improve the post.

Decision order:

1. Use user-provided images or existing project assets first.
2. Use screenshots from the actual workflow when the article teaches a process.
3. Generate or request an image only when a conceptual cover or illustration is valuable.
4. Skip images when the article is stronger as text or when assets would be decorative noise.

For Hexo post assets:

• If _config.yml has post_asset_folder: true, place images beside the post in the generated asset folder and reference them as ./image-name.ext or image-name.ext, following local theme behavior.
• Otherwise place images under source/images/<year-or-topic>/ and reference them with /images/<year-or-topic>/<file>.
• Use lowercase ASCII filenames with hyphens.
• Add meaningful alt text: ![Alt text](path).
• Set cover only when the theme supports it and the image path is valid.

Writing Standards

Write the post for readers, not for the prompt or chat log.

• Start with a concrete problem, tension, question, or promise.
• Prefer precise section headings over generic headings like "Background" or "Conclusion".
• Include code blocks, command blocks, tables, and checklists only where they help the reader act.
• Explain tradeoffs and failed approaches briefly if they teach a decision.
• Keep a clear narrative arc: problem -> insight -> method -> example -> takeaway.
• For Chinese posts, use natural Chinese punctuation and concise paragraphs. Use English technical terms where they are standard.
• For technical posts, verify commands and paths against the real project before presenting them as final.

Final Response

After creating or updating a post, report:

• The created/edited Markdown file path.
• The selected title, categories, and tags.
• The images added or why no image was added.
• The Hexo commands run and whether generation/deployment succeeded.
• Any manual follow-up that remains.

Never claim deployment succeeded unless hexo deploy actually completed successfully.