2.3 KiB

Raw Permalink Blame History

applyTo
layouts/*/.html

Layout and Shortcode Implementation Guidelines

Shortcodes reference: DOCS-SHORTCODES.md Test examples: content/example.md

For detailed Hugo template development workflow, see .claude/skills/hugo-template-dev/SKILL.md which covers:

Hugo template syntax and data access patterns
Build-time vs runtime testing strategies
Shortcode implementation best practices
Complete TDD workflow for Hugo templates

Implementing Shortcodes

When creating or modifying Hugo layouts and shortcodes:

Use test-driven development using /cypress/
Use Hugo template syntax and functions
Follow existing patterns in /layouts/shortcodes/
Test in content/example.md
Document new shortcodes in DOCS-SHORTCODES.md

Shortcode Pattern

<!-- layouts/shortcodes/example.html -->
{{ $param := .Get 0 }}
{{ $namedParam := .Get "name" }}

<div class="example">
  {{ .Inner | markdownify }}
</div>

Testing

IMPORTANT: Use test-driven development with Cypress.

Add shortcode usage examples to content/example.md to verify:

Rendering in browser
Hugo build succeeds
No console errors
JavaScript functionality works as expected (check browser console for errors)
Interactive elements behave correctly (click links, buttons, etc.)

TDD Workflow

Add Cypress tests (high-level to start).
Run tests and make sure they fail.
Implement code changes
Run tests and make sure they pass.
Add and refine tests.
Repeat.

Manual Testing Workflow

Make changes to shortcode/layout files
Wait for Hugo to rebuild (check terminal output)
Get the server URL from the log
Open browser DevTools console (F12)
Test the functionality and check for JavaScript errors
Verify the feature works as intended before marking complete

See DOCS-SHORTCODES.md for complete shortcode documentation.

Complete Hugo template workflow: .claude/skills/hugo-template-dev/SKILL.md
Shortcodes reference: DOCS-SHORTCODES.md
Test examples: content/example.md

2.3 KiB Raw Permalink Blame History