🛠️ Development Guide

This guide provides detailed information for developers working on the Scrum Guide Expansion Pack project.

🌐 Live Sites for Reference

Production: scrumexpansion.org - Live production site
Preview: agreeable-island-0c966e810-preview.centralus.6.azurestaticapps.net - preview environment with latest changes in MAIN
Canary: agreeable-island-0c966e810-{PR-NUMBER}.centralus.6.azurestaticapps.net - Test environment with latest changes in the PR - Deleted after PR closed

Development Environment Setup

Prerequisites

Before starting development, ensure you have:

✅ Hugo Extended (v0.146.0+)
✅ Git (latest version)
✅ PowerShell 7+ (required for automation scripts)
✅ Text Editor/IDE (VS Code recommended)
✅ Node.js (for advanced tooling, optional)

⚠️ Important: This project uses Hugo's new template system introduced in v0.146.0. Earlier Hugo versions are not compatible.

📋 Installation Help: For detailed PowerShell 7+ installation instructions, see the Getting Started Guide.

Installation Verification

# Verify Hugo installation
hugo version

# Verify Git installation
git --version

# Verify you have Hugo Extended
hugo env

Project Setup

1. Clone and Setup

# Clone the repository
git clone https://github.com/ScrumGuides/ScrumGuide-ExpansionPack.git
cd ScrumGuide-ExpansionPack

# Navigate to the Hugo site directory
cd site

# Start development server
hugo server -D --bind 0.0.0.0

2. Development Server Options

# Basic development server
hugo server -D

# With specific port and host binding
hugo server -D --bind 0.0.0.0 --port 1313

# With live reload and draft content
hugo server -D --watch --liveReload

# With specific environment
hugo server -D --environment local

# With verbose logging
hugo server -D --verbose --debug

Code Standards and Guidelines

File Organization

site/
├── content/              # Content files (.md)
├── layouts/              # Templates (.html) - Local overrides only
│   ├── index.html       # Homepage template (local override)
│   ├── categories/      # Category templates (local)
│   ├── creators/        # Creator templates (legacy, local)
│   ├── _partials/       # Reusable template components (local overrides)
│   ├── _markup/         # Render hooks for markdown elements (local)
│   │
│   └── [FROM MODULE: baseof.html, home.html, single.html, list.html]
│       # Base templates provided by github.com/nkdAgility/HugoGuides/module
│       # See hugo.yaml module imports for details
├── static/               # Static assets
├── data/                 # Data files (.yaml/.json)
├── i18n/                 # Translations (.yaml)
└── hugo.yaml            # Configuration (includes module imports)

Important: This site uses Hugo Modules for the majority of its template functionality. Base templates (baseof.html, home.html, single.html, list.html) are provided by the imported module and do not exist in the local layouts/ directory.

Naming Conventions

Files: Use kebab-case (my-file.md)
Directories: Use kebab-case (my-directory/)
Templates: Use kebab-case (my-template.html)
CSS Classes: Use Bootstrap conventions
Variables: Use camelCase in templates

Content Guidelines

Use front matter for all content files
Follow Markdown best practices
Include meta descriptions for SEO
Use semantic HTML in templates
Ensure accessibility compliance

Working with Content

Content Structure

---
title: "Page Title"
description: "Page description for SEO"
date: 2025-06-09
draft: false
weight: 10
language: "en"
---
# Page Content
Your markdown content here...

Creating New Pages

# Create a new extension guide
hugo new content/my-new-guide/_index.md

# Create a new version of a guide
hugo new content/my-new-guide/2026.1/index.md

# Create a guide section
hugo new content/guide/new-section.md

Content Best Practices

Front Matter
- Always include title, description, date
- Use weight for ordering
- Set draft: false when ready to publish
Markdown
- Use semantic heading hierarchy (H1 → H2 → H3)
- Include alt text for images
- Use relative links for internal pages
Images
- Place in /static/images/ directory
- Use descriptive filenames
- Optimize for web (WebP preferred)

Working with Layouts

Template Development (Hugo v0.146.0+ New Template System)

Hugo's new template system uses a simplified structure with enhanced template lookup. The key changes include:

Template Structure Changes

No more _default/ folder: All default templates are now in the root layouts/ directory
Renamed folders: partials/ → _partials/, shortcodes/ → _shortcodes/
New _markup/ folder: For render hooks (links, images, code blocks, etc.)
Simplified naming: index.html → home.html, page-kind-specific templates

Template Development

Hugo uses Go templates with the following structure:

{{ define "main" }}
<main class="container">
  <h1>{{ .Title }}</h1>
  <div class="content">{{ .Content }}</div>
</main>
{{ end }}

New Template Lookup Order

The new template lookup considers these identifiers in order of importance:

Custom Layout - Set in front matter (layout: myCustomLayout)
Page Kinds - home, section, taxonomy, term, page
Standard Layouts - list, single
Output Format - html, rss, json
Language - en, de, es, etc.
Page Path - Specific content paths

Key Template Variables

{{ .Title }} - Page title
{{ .Content }} - Page content
{{ .Params }} - Front matter parameters
{{ .Site }} - Site configuration
{{ .Language }} - Current language

Partial Templates

Create reusable components in /layouts/_partials/ (note the underscore prefix):

<!-- layouts/_partials/components/my-component.html -->
<div class="my-component">
  <h2>{{ .title }}</h2>
  <p>{{ .content }}</p>
</div>

Use in templates:

{{ partial "components/my-component.html" (dict "title" "My Title" "content" "My content") }}

Content-Specific Templates

This site uses Hugo Modules for base templates. You can create local overrides or content-specific templates:

layouts/
├── index.html               # Local homepage override
├── categories/              # Category-specific templates (local)
│   └── list.html
├── creators/                # Creator profiles (legacy, local)
│   ├── single.html
│   └── list.html
├── _partials/               # Local partial overrides
│   ├── components/
│   │   ├── navigation.html
│   │   └── language-switcher.html
│   └── functions/
│       └── get-page-param.html
└── _markup/                 # Custom render hooks (local)
    ├── render-blockquote.html
    └── render-image.html

# Base templates from module (not in local layouts/):
# - baseof.html              # Module-provided base template
# - home.html                # Module-provided homepage
# - single.html              # Module-provided single page
# - list.html                # Module-provided list page

Note: To override a module template, create a file with the same name in your local layouts/ directory.

Internationalization (i18n)

Adding Translations

Create/Update Translation File

# i18n/en.yaml
- id: "welcome"
  translation: "Welcome"

# i18n/de.yaml
- id: "welcome"
  translation: "Willkommen"

Use in Templates
```
<h1>{{ i18n "welcome" }}</h1>
```

Content Translation

Create language-specific content in subdirectories
Use the same file structure for each language
Example: content/en/guide/index.md and content/de/guide/index.md

Styling and CSS

Bootstrap 5 Usage

The project uses Bootstrap 5 as the primary CSS framework:

<!-- Use Bootstrap classes -->
<div class="container">
  <div class="row">
    <div class="col-md-8">
      <p class="lead">Content here</p>
    </div>
  </div>
</div>

Custom CSS

Add custom styles to /static/css/style.css:

/* Custom component styles */
.scrum-guide-content {
  font-family: "Inter", sans-serif;
  line-height: 1.6;
}

.creator-profile {
  border-radius: 0.5rem;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

CSS Best Practices

Use Bootstrap classes first
Create component-specific CSS classes
Follow BEM methodology for custom classes
Ensure responsive design
Test across different screen sizes

Testing and Quality Assurance

Local Testing

# Build the site locally
hugo --environment local

# Check for broken links (if linkchecker is installed)
linkchecker http://localhost:1313

# Validate HTML (if html5validator is installed)
html5validator --root public/

Content Validation

✅ All links work correctly
✅ Images load and have alt text
✅ Meta descriptions are present
✅ Front matter is complete
✅ Markdown syntax is correct

Cross-browser Testing

Test the site in:

✅ Chrome/Chromium
✅ Firefox
✅ Safari (if on macOS)
✅ Edge
✅ Mobile browsers

Debugging and Troubleshooting

Common Issues

Hugo Server Won't Start

# Check Hugo version
hugo version

# Verify you're in the correct directory
cd site

# Check configuration
hugo config

Content Not Appearing

Check front matter has draft: false
Verify file is in correct location
Check template is rendering content
Review Hugo's content organization rules

Styling Issues

Check Bootstrap classes are correct
Verify custom CSS is loaded
Inspect browser developer tools
Clear browser cache

Debug Mode

# Run with debug output
hugo server -D --debug --verbose

# Check configuration
hugo config

# List all content
hugo list all

Performance Optimization

Build Optimization

# Production build with minification
hugo --minify --environment production

# Check build performance
hugo --templateMetrics

Asset Optimization

Images: Use WebP format when possible
CSS: Minimize custom CSS
JavaScript: Only include necessary scripts
Fonts: Use system fonts or optimize web fonts

Git Workflow

Branch Strategy

# Create feature branch
git checkout -b feature/my-new-feature

# Make changes and commit
git add .
git commit -m "feat: add new feature description"

# Push and create pull request
git push origin feature/my-new-feature

Commit Messages

Follow conventional commit format:

feat: - New features
fix: - Bug fixes
docs: - Documentation changes
style: - Code style changes
refactor: - Code refactoring
test: - Test additions/changes

IDE Setup (VS Code)

Recommended Extensions

Hugo Language and Syntax Support
Markdown All in One
YAML
GitLens
Prettier
Bootstrap 5 Quick Snippets

VS Code Settings

{
  "files.associations": {
    "*.html": "html"
  },
  "emmet.includeLanguages": {
    "html": "html"
  }
}

Advanced Development

Custom Shortcodes

Create reusable content components:

<!-- layouts/shortcodes/alert.html -->
<div class="alert alert-{{ .Get 0 }}" role="alert">{{ .Inner }}</div>

Usage in content:

{{< alert "info" >}}
This is an info alert.
{{< /alert >}}

Data Files

Use data files for structured content:

# data/guides.yaml
- name: "Scrum Guide Expanded"
  slug: "scrum-guide-expanded"
  type: "core"
  current_version: "2026.1"

- name: "Complexity"
  slug: "complexity"
  type: "extension"
  current_version: "2026.1"

Access in templates:

{{ range .Site.Data.guides }}
<div class="guide">
  <h3>{{ .name }}</h3>
  <p>Version: {{ .current_version }}</p>
</div>
{{ end }}

Hugo Template System Migration (v0.146.0+)

Note for This Project: This site uses Hugo Modules for template management. Base templates (baseof.html, home.html, single.html, list.html) come from the imported module, not from the local layouts/ directory. The migration notes below apply to Hugo v0.146.0+ in general but are less relevant to this project since most templates are module-provided.

This project uses Hugo's new template system introduced in v0.146.0. Here's what you need to know:

Key Changes Summary

Old System	New System	Action Required
`layouts/_default/`	`layouts/` (root)	Move all `_default` templates to root
`layouts/partials/`	`layouts/_partials/`	Rename folder with underscore prefix
`layouts/shortcodes/`	`layouts/_shortcodes/`	Rename folder with underscore prefix
`layouts/index.html`	`layouts/home.html`	Rename homepage template
`list-baseof.html`	`baseof.list.html`	Move identifier after first dot

Migration Examples

Before (Old Template System)

layouts/
├── _default/
│   ├── baseof.html
│   ├── single.html
│   ├── list.html
│   └── index.html
├── partials/
│   └── header.html
└── shortcodes/
    └── button.html

After (New Template System)

layouts/
├── baseof.html          # Moved from _default/
├── single.html          # Moved from _default/
├── list.html           # Moved from _default/
├── home.html           # Renamed from index.html
├── _partials/          # Renamed from partials/
│   └── header.html
└── _shortcodes/        # Renamed from shortcodes/
    └── button.html

Template Lookup Changes

The new system uses a more intuitive lookup order:

Custom Layout - Set in front matter (layout: custom)
Page Kind - home, section, taxonomy, term, page
Standard Layout - list, single, all
Output Format - html, rss, json
Language - en, de, es
Page Path - Content-specific paths

Path-Based Templates

You can now organize templates by content structure:

layouts/
├── baseof.html              # Global base template
├── home.html               # Homepage
├── single.html             # Default single page
├── guide/                  # Guide-specific templates
│   ├── single.html        # Override for guide pages
│   └── list.html          # Override for guide lists
└── creators/               # Creator-specific templates
    └── single.html        # Override for creator pages

Internal Template Changes

Replace internal template calls with partials:

<!-- Old Way -->
{{ template "_internal/opengraph.html" . }}

<!-- New Way -->
{{ partial "opengraph.html" . }}

Upgrading Notes

Minimum Version: Hugo Extended v0.146.0 or higher
Breaking Changes: Some old template calls may not work
Testing Required: Verify all templates render correctly
Documentation: Update any custom documentation

For more details, see the official Hugo template system overview.

CI/CD Integration

The project uses GitHub Actions for automated builds and deployments. See deployment configuration in .github/workflows/.

Local Build Testing

Before pushing, test the build locally:

# Test production build
hugo --environment production --minify

# Verify output
cd public
ls -la

🔙 Back to: Documentation Home
➡️ Next: Deployment Guide

FilesExpand file tree

development.md

Latest commit

History