hugo-template-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hugo Template Development Skill

Hugo模板开发技能

Purpose

目的

This skill enforces proper Hugo template development practices, including mandatory runtime testing to catch errors that static builds miss.

本技能规范Hugo模板开发实践，包括强制运行时测试，以捕获静态构建无法发现的错误。

Critical Testing Requirement

关键测试要求

Hugo's
npx hugo --quiet
only validates template syntax, not runtime execution.

Template errors like accessing undefined fields, nil values, or incorrect type assertions only appear when Hugo actually renders pages. You MUST test templates by running the server.

Hugo的
npx hugo --quiet
仅验证模板语法，不检查运行时执行情况。

诸如访问未定义字段、空值或类型断言错误之类的模板问题，只有在Hugo实际渲染页面时才会显现。你必须通过运行服务器来测试模板。

Mandatory Testing Protocol

强制测试流程

For ANY Hugo Template Change

针对所有Hugo模板变更

After modifying files in

layouts/

layouts/partials/

, or

layouts/shortcodes/

Step 1: Start Hugo server and capture output

bash

npx hugo server --port 1315 2>&1 | head -50

Success criteria:

No
```
error calling partial
```
messages
No
```
can't evaluate field
```
errors
No
```
template: ... failed
```
messages
Server shows "Web Server is available at http://localhost:1315/"

If errors appear: Fix the template and repeat Step 1 before proceeding.

Step 2: Verify the page renders

bash

curl -s -o /dev/null -w "%{http_code}" http://localhost:1315/PATH/TO/PAGE/

Expected: HTTP 200 status code

Step 3: Browser testing (if MCP browser tools available)

mcp__claude-in-chrome__*

tools are available, use them for visual inspection:

undefined

修改

layouts/

、

layouts/partials/

或

layouts/shortcodes/

下的文件后：

步骤1：启动Hugo服务器并捕获输出

bash

npx hugo server --port 1315 2>&1 | head -50

成功标准：

无
```
error calling partial
```
提示
无
```
can't evaluate field
```
错误
无
```
template: ... failed
```
提示
服务器显示"Web Server is available at http://localhost:1315/"

若出现错误： 修复模板后重复步骤1，再继续后续操作。

步骤2：验证页面可正常渲染

bash

curl -s -o /dev/null -w "%{http_code}" http://localhost:1315/PATH/TO/PAGE/

预期结果： HTTP 200状态码

步骤3：浏览器测试（若有MCP浏览器工具）

若

mcp__claude-in-chrome__*

工具可用，可使用它们进行视觉检查：

undefined

Navigate and screenshot

导航并截图

mcp__claude-in-chrome__navigate({ url: "http://localhost:1315/PATH/", tabId: ... }) mcp__claude-in-chrome__computer({ action: "screenshot", tabId: ... })

Check for JavaScript errors

检查JavaScript错误

mcp__claude-in-chrome__read_console_messages({ tabId: ..., onlyErrors: true })


This catches runtime JavaScript errors that template changes may introduce.

**Step 4: Stop the test server**

```bash
pkill -f "hugo server --port 1315"

mcp__claude-in-chrome__read_console_messages({ tabId: ..., onlyErrors: true })


这可以捕获模板变更可能引入的运行时JavaScript错误。

**步骤4：停止测试服务器**

```bash
pkill -f "hugo server --port 1315"

Quick Test Command

快速测试命令

Use this one-liner to test and get immediate feedback:

bash

timeout 15 npx hugo server --port 1315 2>&1 | grep -E "(error|Error|ERROR|fail|FAIL)" | head -20; pkill -f "hugo server --port 1315" 2>/dev/null

If output is empty, no errors were detected.

使用以下单行命令进行测试并获取即时反馈：

bash

timeout 15 npx hugo server --port 1315 2>&1 | grep -E "(error|Error|ERROR|fail|FAIL)" | head -20; pkill -f "hugo server --port 1315" 2>/dev/null

若无输出，则未检测到错误。

Common Hugo Template Errors

常见Hugo模板错误

1. Accessing Hyphenated Keys

1. 访问带连字符的键

Wrong:

{{ .Site.Data.article-data.influxdb }}

Correct:

{{ index .Site.Data "article-data" "influxdb" }}

错误写法：

{{ .Site.Data.article-data.influxdb }}

正确写法：

{{ index .Site.Data "article-data" "influxdb" }}

2. Nil Field Access

2. 访问空字段

Wrong:

{{ range $articles }}
  {{ .path }}  {{/* Fails if item is nil or wrong type */}}
{{ end }}

Correct:

{{ range $articles }}
  {{ if . }}
    {{ with index . "path" }}
      {{ . }}
    {{ end }}
  {{ end }}
{{ end }}

错误写法：

{{ range $articles }}
  {{ .path }}  {{/* 若条目为空或类型错误会失败 */}}
{{ end }}

正确写法：

{{ range $articles }}
  {{ if . }}
    {{ with index . "path" }}
      {{ . }}
    {{ end }}
  {{ end }}
{{ end }}

3. Type Assertion on Interface{}

3. 对Interface{}进行类型断言

Wrong:

{{ range $data }}
  {{ .fields.menuName }}
{{ end }}

Correct:

{{ range $data }}
  {{ if isset . "fields" }}
    {{ $fields := index . "fields" }}
    {{ if isset $fields "menuName" }}
      {{ index $fields "menuName" }}
    {{ end }}
  {{ end }}
{{ end }}

错误写法：

{{ range $data }}
  {{ .fields.menuName }}
{{ end }}

正确写法：

{{ range $data }}
  {{ if isset . "fields" }}
    {{ $fields := index . "fields" }}
    {{ if isset $fields "menuName" }}
      {{ index $fields "menuName" }}
    {{ end }}
  {{ end }}
{{ end }}

4. Empty Map vs Nil Check

4. 空Map与空值检查

Problem: Hugo's

{{ if . }}

passes for empty maps

{}

{{/* This doesn't catch empty maps */}}
{{ if $data }}
  {{ .field }}  {{/* Still fails if $data is {} */}}
{{ end }}

Solution: Check for specific keys:

{{ if and $data (isset $data "field") }}
  {{ index $data "field" }}
{{ end }}

问题： Hugo的

{{ if . }}

会将空Map

{}

判定为真：

{{/* 无法捕获空Map */}}
{{ if $data }}
  {{ .field }}  {{/* 若$data为{}仍会失败 */}}
{{ end }}

解决方案： 检查特定键是否存在：

{{ if and $data (isset $data "field") }}
  {{ index $data "field" }}
{{ end }}

Hugo Data Access Patterns

Hugo数据访问模式

Safe Nested Access

安全嵌套访问

{{/* Build up access with nil checks at each level */}}
{{ $articleDataRoot := index .Site.Data "article-data" }}
{{ if $articleDataRoot }}
  {{ $influxdbData := index $articleDataRoot "influxdb" }}
  {{ if $influxdbData }}
    {{ $productData := index $influxdbData $dataKey }}
    {{ if $productData }}
      {{ with $productData.articles }}
        {{/* Safe to use . here */}}
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

{{/* 逐层构建访问并添加空值检查 */}}
{{ $articleDataRoot := index .Site.Data "article-data" }}
{{ if $articleDataRoot }}
  {{ $influxdbData := index $articleDataRoot "influxdb" }}
  {{ if $influxdbData }}
    {{ $productData := index $influxdbData $dataKey }}
    {{ if $productData }}
      {{ with $productData.articles }}
        {{/* 此处可安全使用. */}}
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

Iterating Over Data Safely

安全遍历数据

{{ range $idx, $item := $articles }}
  {{/* Declare variables with defaults */}}
  {{ $path := "" }}
  {{ $name := "" }}

  {{/* Safely extract values */}}
  {{ if isset $item "path" }}
    {{ $path = index $item "path" }}
  {{ end }}

  {{ if $path }}
    {{/* Now safe to use $path */}}
  {{ end }}
{{ end }}

{{ range $idx, $item := $articles }}
  {{/* 声明带默认值的变量 */}}
  {{ $path := "" }}
  {{ $name := "" }}

  {{/* 安全提取值 */}}
  {{ if isset $item "path" }}
    {{ $path = index $item "path" }}
  {{ end }}

  {{ if $path }}
    {{/* 现在可安全使用$path */}}
  {{ end }}
{{ end }}

File Organization

文件组织

Layouts Directory Structure

Layouts目录结构

layouts/
├── _default/           # Default templates
├── partials/           # Reusable template fragments
│   └── api/            # API-specific partials
├── shortcodes/         # Content shortcodes
└── TYPE/               # Type-specific templates (api/, etc.)
    └── single.html     # Single page template

layouts/
├── _default/           # 默认模板
├── partials/           # 可复用模板片段
│   └── api/            # API相关片段
├── shortcodes/         # 内容短代码
└── TYPE/               # 类型特定模板（如api/）
    └── single.html     # 单页模板

Partial Naming

片段命名规范

Use descriptive names:
```
api/sidebar-nav.html
```
, not
```
nav.html
```
Group related partials in subdirectories
Include comments at the top describing purpose and required context

使用描述性名称：
```
api/sidebar-nav.html
```
，而非
```
nav.html
```
将相关片段归类到子目录中
在顶部添加注释说明用途和所需上下文

Separation of Concerns: Templates vs TypeScript

关注点分离：模板与TypeScript

Principle: Hugo templates handle structure and data binding. TypeScript handles behavior and interactivity.

原则： Hugo模板负责结构和数据绑定。TypeScript负责行为和交互。

What Goes Where

职责划分

Concern	Location	Example
HTML structure	`layouts/*/.html`	Navigation markup, tab containers
Data binding	`layouts/*/.html`	`{{ .Title }}` , `{{ range .Data }}`
Static styling	`assets/styles/*/.scss`	Layout, colors, typography
User interaction	`assets/js/components/*.ts`	Click handlers, scroll behavior
State management	`assets/js/components/*.ts`	Active tabs, collapsed sections
DOM manipulation	`assets/js/components/*.ts`	Show/hide, class toggling

关注点	存放位置	示例
HTML结构	`layouts/*/.html`	导航标记、标签容器
数据绑定	`layouts/*/.html`	`{{ .Title }}` , `{{ range .Data }}`
静态样式	`assets/styles/*/.scss`	布局、颜色、排版
用户交互	`assets/js/components/*.ts`	点击处理、滚动行为
状态管理	`assets/js/components/*.ts`	激活标签、折叠区域
DOM操作	`assets/js/components/*.ts`	显示/隐藏、类切换

Anti-Pattern: Inline JavaScript in Templates

反模式：模板中内嵌JavaScript

Wrong - JavaScript mixed with template:

html

{{/* DON'T DO THIS */}}
<nav class="api-nav">
  {{ range $articles }}
    <button onclick="toggleSection('{{ .id }}')">{{ .name }}</button>
  {{ end }}
</nav>

<script>
function toggleSection(id) {
  document.getElementById(id).classList.toggle('is-open');
}
</script>

Correct - Clean separation:

Template (

layouts/partials/api/sidebar-nav.html

html

<nav class="api-nav" data-component="api-nav">
  {{ range $articles }}
    <button class="api-nav-group-header" aria-expanded="false">
      {{ .name }}
    </button>
    <ul class="api-nav-group-items">
      {{/* items */}}
    </ul>
  {{ end }}
</nav>

TypeScript (

assets/js/components/api-nav.ts

typescript

interface ApiNavOptions {
  component: HTMLElement;
}

export default function initApiNav({ component }: ApiNavOptions): void {
  const headers = component.querySelectorAll('.api-nav-group-header');

  headers.forEach((header) => {
    header.addEventListener('click', () => {
      const isOpen = header.classList.toggle('is-open');
      header.setAttribute('aria-expanded', String(isOpen));
      header.nextElementSibling?.classList.toggle('is-open', isOpen);
    });
  });
}

main.js

javascript

import initApiNav from './components/api-nav.js';

const componentRegistry = {
  'api-nav': initApiNav,
  // ... other components
};

错误写法 - JavaScript与模板混合：

html

{{/* 请勿这样做 */}}
<nav class="api-nav">
  {{ range $articles }}
    <button onclick="toggleSection('{{ .id }}')">{{ .name }}</button>
  {{ end }}
</nav>

<script>
function toggleSection(id) {
  document.getElementById(id).classList.toggle('is-open');
}
</script>

正确写法 - 清晰分离：

模板（

layouts/partials/api/sidebar-nav.html

）：

html

<nav class="api-nav" data-component="api-nav">
  {{ range $articles }}
    <button class="api-nav-group-header" aria-expanded="false">
      {{ .name }}
    </button>
    <ul class="api-nav-group-items">
      {{/* 条目内容 */}}
    </ul>
  {{ end }}
</nav>

TypeScript（

assets/js/components/api-nav.ts

）：

typescript

interface ApiNavOptions {
  component: HTMLElement;
}

export default function initApiNav({ component }: ApiNavOptions): void {
  const headers = component.querySelectorAll('.api-nav-group-header');

  headers.forEach((header) => {
    header.addEventListener('click', () => {
      const isOpen = header.classList.toggle('is-open');
      header.setAttribute('aria-expanded', String(isOpen));
      header.nextElementSibling?.classList.toggle('is-open', isOpen);
    });
  });
}

在

main.js

中注册：

javascript

import initApiNav from './components/api-nav.js';

const componentRegistry = {
  'api-nav': initApiNav,
  // ... 其他组件
};

Data Passing Pattern

数据传递模式

Pass Hugo data to TypeScript via

data-*

attributes:

Template:

html

<div
  data-component="api-toc"
  data-headings="{{ .headings | jsonify | safeHTMLAttr }}"
  data-scroll-offset="80"
>
</div>

TypeScript:

typescript

interface TocOptions {
  component: HTMLElement;
}

interface TocData {
  headings: string[];
  scrollOffset: number;
}

function parseData(component: HTMLElement): TocData {
  const headingsRaw = component.dataset.headings;
  const headings = headingsRaw ? JSON.parse(headingsRaw) : [];
  const scrollOffset = parseInt(component.dataset.scrollOffset || '0', 10);

  return { headings, scrollOffset };
}

export default function initApiToc({ component }: TocOptions): void {
  const data = parseData(component);
  // Use data.headings and data.scrollOffset
}

通过

data-*

属性将Hugo数据传递给TypeScript：

模板：

html

<div
  data-component="api-toc"
  data-headings="{{ .headings | jsonify | safeHTMLAttr }}"
  data-scroll-offset="80"
>
</div>

TypeScript：

typescript

interface TocOptions {
  component: HTMLElement;
}

interface TocData {
  headings: string[];
  scrollOffset: number;
}

function parseData(component: HTMLElement): TocData {
  const headingsRaw = component.dataset.headings;
  const headings = headingsRaw ? JSON.parse(headingsRaw) : [];
  const scrollOffset = parseInt(component.dataset.scrollOffset || '0', 10);

  return { headings, scrollOffset };
}

export default function initApiToc({ component }: TocOptions): void {
  const data = parseData(component);
  // 使用data.headings和data.scrollOffset
}

Minimal Inline Scripts (Exception)

允许的内嵌脚本（例外情况）

The only acceptable inline scripts are minimal initialization that MUST run before component registration:

html

{{/* Acceptable: Critical path, no logic, runs immediately */}}
<script>
  document.documentElement.dataset.theme =
    localStorage.getItem('theme') || 'light';
</script>

Everything else belongs in

assets/js/

唯一可接受的内嵌脚本是必须在组件注册前运行的最小化初始化代码：

html

{{/* 可接受：关键路径，无逻辑，立即执行 */}}
<script>
  document.documentElement.dataset.theme =
    localStorage.getItem('theme') || 'light';
</script>

其他所有代码都应放在

assets/js/

中。

TypeScript Component Checklist

TypeScript组件检查清单

When creating a new interactive feature:

Create TypeScript file in
```
assets/js/components/
```
Define interface for component options
Export default initializer function
Register in
```
main.js
```
componentRegistry
Add
```
data-component
```
attribute to HTML element
Pass data via
```
data-*
```
attributes (not inline JS)
NO inline
<script>
tags in templates

创建新交互功能时：

在
```
assets/js/components/
```
中创建TypeScript文件
定义组件选项的接口
导出默认初始化函数
在
```
main.js
```
的componentRegistry中注册
为HTML元素添加
```
data-component
```
属性
通过
```
data-*
```
属性传递数据（而非内嵌JS）
模板中禁止内嵌
<script>
标签

Debugging Templates

模板调试

Enable Verbose Mode

启用详细模式

bash

npx hugo server --port 1315 --verbose 2>&1 | head -100

bash

npx hugo server --port 1315 --verbose 2>&1 | head -100

Print Variables for Debugging

打印变量用于调试

{{/* Temporary debugging - REMOVE before committing */}}
<pre>{{ printf "%#v" $myVariable }}</pre>

{{/* 临时调试 - 提交前请移除 */}}
<pre>{{ printf "%#v" $myVariable }}</pre>

Check Data File Loading

检查数据文件加载情况

bash

undefined

bash

undefined

Verify data files exist and are valid YAML

验证数据文件存在且为有效YAML

cat data/article-data/influxdb/influxdb3-core/articles.yml | head -20

undefined

cat data/article-data/influxdb/influxdb3-core/articles.yml | head -20

undefined

Integration with CI/CD

与CI/CD集成

Pre-commit Hook (Recommended)

预提交钩子（推荐）

Add to

.lefthook.yml

or pre-commit configuration:

yaml

pre-commit:
  commands:
    hugo-template-test:
      glob: "layouts/**/*.html"
      run: |
        timeout 20 npx hugo server --port 1315 2>&1 | grep -E "error|Error" && exit 1 || exit 0
        pkill -f "hugo server --port 1315" 2>/dev/null

添加到

.lefthook.yml

或预提交配置中：

yaml

pre-commit:
  commands:
    hugo-template-test:
      glob: "layouts/**/*.html"
      run: |
        timeout 20 npx hugo server --port 1315 2>&1 | grep -E "error|Error" && exit 1 || exit 0
        pkill -f "hugo server --port 1315" 2>/dev/null

GitHub Actions Workflow

GitHub Actions工作流

yaml

- name: Test Hugo templates
  run: |
    npx hugo server --port 1315 &
    sleep 10
    curl -f http://localhost:1315/ || exit 1
    pkill -f hugo

yaml

- name: Test Hugo templates
  run: |
    npx hugo server --port 1315 &
    sleep 10
    curl -f http://localhost:1315/ || exit 1
    pkill -f hugo

Quick Reference

快速参考

Action	Command
Test templates (runtime)	`npx hugo server --port 1315 2>&1 \| head -50`
Build only (insufficient)	`npx hugo --quiet`
Check specific page	`curl -s -o /dev/null -w "%{http_code}" http://localhost:1315/path/`
Stop test server	`pkill -f "hugo server --port 1315"`
Debug data access	`<pre>{{ printf "%#v" $var }}</pre>`

操作	命令
测试模板（运行时）	`npx hugo server --port 1315 2>&1 \| head -50`
仅构建（测试不充分）	`npx hugo --quiet`
检查特定页面	`curl -s -o /dev/null -w "%{http_code}" http://localhost:1315/path/`
停止测试服务器	`pkill -f "hugo server --port 1315"`
调试数据访问	`<pre>{{ printf "%#v" $var }}</pre>`

Remember

注意事项

Never trust
npx hugo --quiet
alone - it only checks syntax
Always run the server to test template changes
Check error output first before declaring success
Use
isset
and
index
for safe data access
Hyphenated keys require
index
function - dot notation fails

永远不要只依赖
npx hugo --quiet
- 它仅检查语法
始终运行服务器来测试模板变更
先检查错误输出再确认测试通过
**使用
```
isset
```
和
```
index
```
**进行安全数据访问
带连字符的键需要使用
index
函数 - 点语法会失效

hugo-template-dev

Original

Translation

Hugo Template Development Skill

Hugo模板开发技能

Purpose

目的

Critical Testing Requirement

关键测试要求

Mandatory Testing Protocol

强制测试流程

For ANY Hugo Template Change

针对所有Hugo模板变更

Navigate and screenshot

导航并截图

Check for JavaScript errors

检查JavaScript错误

Quick Test Command

快速测试命令

Common Hugo Template Errors

常见Hugo模板错误

1. Accessing Hyphenated Keys

1. 访问带连字符的键

2. Nil Field Access

2. 访问空字段

3. Type Assertion on Interface{}

3. 对Interface{}进行类型断言

4. Empty Map vs Nil Check

4. 空Map与空值检查

Hugo Data Access Patterns

Hugo数据访问模式

Safe Nested Access

安全嵌套访问

Iterating Over Data Safely

安全遍历数据

File Organization

文件组织

Layouts Directory Structure

Layouts目录结构

Partial Naming

片段命名规范

Separation of Concerns: Templates vs TypeScript

关注点分离：模板与TypeScript

What Goes Where

职责划分

Anti-Pattern: Inline JavaScript in Templates

反模式：模板中内嵌JavaScript

Data Passing Pattern

数据传递模式

Minimal Inline Scripts (Exception)

允许的内嵌脚本（例外情况）

TypeScript Component Checklist

TypeScript组件检查清单

Debugging Templates

模板调试

Enable Verbose Mode

启用详细模式

Print Variables for Debugging

打印变量用于调试

Check Data File Loading

检查数据文件加载情况

Verify data files exist and are valid YAML

验证数据文件存在且为有效YAML

Integration with CI/CD

与CI/CD集成

Pre-commit Hook (Recommended)

预提交钩子（推荐）

GitHub Actions Workflow

GitHub Actions工作流

Quick Reference

快速参考

Remember

注意事项

Related Skills

相关技能