AIHeadline News Hugo Site Manager

This skill helps you work with AIHeadline.news, an automated AI news aggregation site built with Hugo and the Hextra theme. Content is dynamically generated from the `ai-briefing-archive` repository and deployed to both Cloudflare Workers and GitHub Pages.

Core Architecture Principle

**CRITICAL**: The `content/` and `source-news/` directories are **NOT** committed to git. They are dynamically generated during CI/CD builds by fetching and processing external news data.

Development Workflows

Local Development Setup

When the user wants to start local development:

1. Run the quick start script:

```bash

bash .github/scripts/dev.sh

```

This script syncs content and starts the Hugo dev server.

2. If manual control is needed:

```bash

# Fetch latest news data

./.github/scripts/update-source-news.sh

# Sync content to Hugo format

./.github/scripts/sync-news.sh --mode=auto

# Start Hugo development server

hugo server

```

Content Sync Modes

The `sync-news.sh` script supports three modes:

Building the Site

For production builds:

```bash

Build static site

hugo --gc --minify

For Cloudflare Worker development (requires .dev.vars with GA4_SERVICE_KEY)

npm run dev

```

Content Generation Pipeline

Phase 1: Source Fetch

The `update-source-news.sh` script:

Phase 2: Content Transformation

The `sync-news.sh` script:

- Title: Localized date in Chinese (e.g., "10月17日 AI 快讯")

- Weight: Calculated for reverse chronological sorting

- Sources array: Display names extracted from H1 headers

Phase 3: Dual Build System

Two independent builds are created:

Hugo + Hextra Theme Integration

Critical Theme Constraint

All content pages inherit `cascade: type: docs` from `content/_index.md`. This affects:

RSS Feed Configuration

**CRITICAL**: RSS template location matters for Hugo + Hextra:

**Why**: Hugo's template lookup order prioritizes page-kind-specific templates (`index.rss.xml`) over default templates. For homepage RSS with themes that use custom page types, use the explicit `index.rss.xml` path.

Cloudflare Worker Features

The `_worker.ts` file implements:

Required Environment Variables

For Cloudflare Worker deployment:

Troubleshooting Common Issues

Empty RSS Feed

**Symptoms**: `index.xml` contains channel info but no `<item>` elements

**Diagnosis**:

1. Check if RSS template is at `layouts/index.rss.xml` (not `_default/rss.xml`)

2. Verify page collection method in template uses `site.RegularPages.ByDate.Reverse`

3. Remember: content pages inherit `type: docs` from cascade

**Solution**: Move or create RSS template at `layouts/index.rss.xml`

Content Not Updating

**Symptoms**: New briefings don't appear after deployment

**Diagnosis**:

1. Check GitHub Actions logs for `update-source-news.sh` step

2. Verify `sync-news.sh` output shows expected date processing

3. Confirm Hugo build shows correct page count in build output (look for "Pages │ XX")

**Solution**: Re-run content sync scripts or check source repository update status

Hugo Module Errors

**Symptoms**: Build fails with "module not found" for Hextra theme

**Requirements**:

**Solution**: Hugo automatically downloads modules on first build if above requirements are met

File Structure Reference

```

layouts/

├── index.rss.xml # Homepage RSS feed (CRITICAL: exact path required)

├── _default/

│ ├── list.markdown # Markdown output format

│ └── single.markdown

├── partials/

│ └── custom-head.html # GA4 + AdSense injection

└── shortcodes/ # Custom Hugo shortcodes

```

Git-Ignored Directories

These directories are generated and should NOT be committed:

Deployment Flow

GitHub Actions triggers on:

Build produces two independent artifacts:

1. **site-worker** → Deployed to Cloudflare Workers

2. **pages artifact** → Deployed to GitHub Pages

Both use the same Hugo source but different base URLs.

Key Hugo Configuration

From `hugo.toml`:

Instructions for AI Agent

When working with this codebase:

1. **Never commit generated content**: Always check that changes to `content/` or `source-news/` are not staged for commit

2. **Use sync scripts**: Don't manually edit files in `content/` - they will be overwritten. Modify source data or sync scripts instead

3. **RSS template location**: If fixing RSS issues, always use `layouts/index.rss.xml`, never `_default/rss.xml`

4. **Test locally first**: Run `bash .github/scripts/dev.sh` before suggesting deployment changes

5. **Dual deployment awareness**: Remember that changes affect both Cloudflare Workers and GitHub Pages builds

6. **Hugo version**: Ensure Hugo extended ≥ 0.150.0 for all build operations

7. **Content sync modes**: Use `--mode=auto` for most cases, `--mode=full` for major structural changes, `--mode=incremental` with `--dates` for targeted updates