Development Guide - ScrumGuides/ScrumGuide-ExpansionPack GitHub Wiki

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

• Production: scrumexpansion.org - Live production site
• Preview: agreeable-island-0c966e810-preview.centralus.6.azurestaticapps.net - Test environment with latest changes

Before starting -Development-Guide, ensure you have:

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

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

# Verify Hugo installation
hugo version

# Verify Git installation
git --version

# Verify you have Hugo Extended
hugo env

# 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-Guide server
hugo server -D --bind 0.0.0.0

# Basic -Development-Guide 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

site/
├── content/              # Content files (.md)
├── layouts/              # Templates (.html)
├── static/               # Static assets
├── data/                 # Data files (.yaml/.json)
├── i18n/                 # Translation-Guide (.yaml)
└── hugo.yaml            # -Configuration-Reference

• 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

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

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

# Create a new page
hugo new content/your-page.md

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

# Create a creator profile
hugo new content/creators/new-creator/index.md

1. Front Matter

   • Always include title, description, date
   • Use weight for ordering
   • Set draft: false when ready to publish

2. Markdown

   • Use semantic heading hierarchy (H1 → H2 → H3)
   • Include alt text for images
   • Use relative links for internal pages

3. Images

   • Place in /static/images/ directory
   • Use descriptive filenames
   • Optimize for web (WebP preferred)

Hugo uses Go templates with the following structure:

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

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

Create reusable components in /layouts/partials/:

<!-- 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") }}

1. Create/Update Translation File

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

2. Use in Templates

   <h1>{{ i18n "welcome" }}</h1>

• 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

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>

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);
}

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

# 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/

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

Test the site in:

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

# Check Hugo version
hugo version

# Verify you're in the correct directory
cd site

# Check -Configuration-Reference
hugo config

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

1. Check Bootstrap classes are correct
2. Verify custom CSS is loaded
3. Inspect browser developer tools
4. Clear browser cache

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

# Check -Configuration-Reference
hugo config

# List all content
hugo list all

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

# Check build performance
hugo --templateMetrics

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

# 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

Follow conventional commit format:

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

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

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

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 >}}

Use data files for structured content:

# data/creators.yaml
- name: "Ralph Jocham"
  role: "Scrum Trainer"
  image: "ralph-jocham.jpg"

- name: "John Coleman"
  role: "Agile Coach"

Access in templates:

{{ range .Site.Data.creators }}
<div class="creator">
  <h3>{{ .name }}</h3>
  <p>{{ .role }}</p>
</div>
{{ end }}

The project uses GitHub Actions for automated builds and -Deployment-Guides. See -Deployment-Guide -Configuration-Reference in .github/workflows/.

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 Guide