Hugo Init

Hugo + Blowfish Blog Initialization

Set up a new Hugo + Blowfish blog project with all necessary configuration, GitHub Pages deployment, and blog plugin integration.

Prerequisites Check

1. Verify Hugo is installed: hugo version (require v0.112.0+)
2. Verify git is available: git --version
3. If Hugo is missing, provide installation instructions for the detected OS

Workflow

1. Create Hugo Site

hugo new site <site-name> --format yaml
cd <site-name>
git init

If no site-name argument provided, ask for one.

2. Add Blowfish Theme

git submodule add https://github.com/nunocoracao/blowfish.git themes/blowfish

3. Configure Hugo

Create config/_default/ directory with these files:

• config.yaml: baseURL, languageCode, title, theme: blowfish
• params.yaml: Blowfish parameters (homepage layout, article settings, showReadingTime, showWordCount, showDate, colorScheme)
• menus.yaml: Main navigation (Home, Posts, Tags, About)
• languages.yaml: Default language configuration
• markup.yaml: Goldmark settings, Mermaid support

Enable Mermaid diagram support in Blowfish config.

4. Configure Giscus Comments

Prompt for GitHub repository (for Giscus discussions). Add Giscus configuration to params.yaml. If user doesn't have a repo yet, skip and add instructions for later setup.

5. Create Content Structure

content/
  posts/          # Blog posts live here
  about/          # About page

Create a stub about page.

6. Set Up Blog Plugin Integration

If the blog plugin is installed (check for blog:brainstorm skill availability):

• Create .claude/blog/ directory
• Copy brainstorm template if available
• Create .claude/blog.local.md with default configuration (prompt for social accounts, analytics, vault path)
• Create brainstorm/00-overview.md (empty pipeline index)

7. Set Up Style and Voice Configuration

Set up the .style/ directory so cc-prose and cc-copyedit work correctly in this project.

Directory structure to create:

.style/
  config.yaml         # Prose/copyedit thresholds for blog context
  styleguide.md       # Blog-specific style rules
  stoplist.txt        # Forbidden AI words (extends global)
  wordlist.txt        # Preferred terminology
  voice.yaml          # Active project voice (symlink or copy of blog.yaml)
  voices/             # All blog voice variants
    blog.yaml
    blog-pov.yaml
    blog-reasoning.yaml
    blog-narrative.yaml

Steps:

1. Create .style/ and .style/voices/ directories
2. If the blog plugin is installed, copy voice profiles from the blog plugin to the project:

   cp ${BLOG_PLUGIN_ROOT}/knowledge-base/voice-profiles/*.yaml .style/voices/
   

3. Copy the default blog voice as the active project voice:

   cp .style/voices/blog.yaml .style/voice.yaml
   

4. Also install to the global location (so other tools can find them):

   mkdir -p ~/.claude/style/voices
   cp .style/voices/*.yaml ~/.claude/style/voices/
   

5. Create .style/config.yaml with blog-appropriate thresholds:

   severity_threshold: medium
   style:
     target_sentence_length: 19
     max_sentence_length: 40
     target_active_voice_pct: 75
   

6. Create .style/stoplist.txt with blog-specific forbidden words:

   # Blog stoplist (extends global ~/.claude/style/stoplist.txt)
   delve -> explore, examine
   leverage -> use, apply
   utilize -> use
   robust -> reliable, strong
   comprehensive -> complete, thorough
   crucial -> critical, key, important
   

7. Create a minimal .style/styleguide.md with blog conventions

Why project-local voices matter: Voice profiles in .style/voices/ travel with the git repo. Anyone cloning the blog project gets the voices automatically, without needing them installed globally. The prose plugin resolves voices from .style/voices/ (project) before ~/.claude/style/voices/ (global).

8. Set Up GitHub Pages Deployment

Create .github/workflows/hugo.yml with the official Hugo GitHub Pages workflow. Configure for the Blowfish theme.

9. Create .gitignore

public/
resources/
.hugo_build.lock
.DS_Store
.claude/*.local.md

10. Initial Commit

git add -A
git commit -m "Initial blog setup with Hugo + Blowfish"

11. Dependency Check

Check for recommended plugins and report status:

• blog (cc-blog): Required for content pipeline management
• cc-prose: Required for content generation
• cc-copyedit: Recommended for post-production editing

Provide installation commands for any missing plugins.

Post-Init Instructions

After initialization, present:

• How to preview: /hugo:preview
• How to create first post: /blog:brainstorm (if blog plugin available)
• How to migrate old posts: /hugo:migrate
• How to generate legal pages: /hugo:legal