Getting Started - ScrumGuides/ScrumGuide-ExpansionPack GitHub Wiki

This guide will help you set up your -Development-Guide environment and get the Scrum Guide Expansion Pack project running locally.

Before you begin, ensure you have the following installed on your system:

1. Git - Version control system

   • Download Git
   • Verify installation: git --version

2. Hugo Extended - Static site generator

   • Windows: choco install hugo-extended (using Chocolatey)
   • macOS: brew install hugo (using Homebrew)
   • Linux: snap install hugo (using Snap)
   • Verify installation: hugo version
   • Required version: Hugo v0.118.0 or higher (Extended version)

3. PowerShell 7+ - Required for automation scripts

   • Windows: Install PowerShell 7+
   • macOS: Install PowerShell on macOS
   • Linux: Install PowerShell on Linux
   • Purpose: Required for running Create-GuidePDFs.ps1 and Create-TranslationTemplate.ps1
   • Verify installation: pwsh --version

4. Text Editor (recommended)

   • Visual Studio Code with Hugo extensions
   • IntelliJ IDEA
   • Any text editor of your choice

1. Node.js and npm - For additional tooling and dependencies

   • Download Node.js
   • Used for Prettier formatting and additional build tools

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

# Navigate to the project directory
cd ScrumGuide-ExpansionPack

# Check Hugo version (should be Extended version)
hugo version

# Expected output should include "extended"
# Example: hugo v0.118.2+extended windows/amd64

If you plan to use additional tooling:

# Install Node.js dependencies for formatting and linting
npm install

# Navigate to the Hugo site directory
cd site

# Start the -Development-Guide server
hugo server -D --bind 0.0.0.0

# Alternative with live reload and drafts
hugo server --buildDrafts --buildFuture --bind 0.0.0.0

Navigate to http://localhost:1313 to view the site locally.

To see how your local changes compare with the live sites:

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

This project includes PowerShell automation scripts to help with common tasks:

1. scripts/Create-GuidePDFs.ps1 - Generates PDF versions of the guide

   • Creates PDFs for all available languages
   • Requires Pandoc and LaTeX installation
   • See PDF Generation Guide for details

2. scripts/Create-TranslationTemplate.ps1 - Sets up new language Translation-Guide

   • Automatically configures Hugo for new languages
   • Creates translation template files
   • See Translation Guide for details

If you don't have PowerShell 7+ installed:

# Using Windows Package Manager (winget)
winget install Microsoft.PowerShell

# Using Chocolatey
choco install powershell-core

# Or download MSI from: https://github.com/PowerShell/PowerShell/releases

# Using Homebrew
brew install powershell

# Using MacPorts
sudo port install powershell

# Download and install
wget https://github.com/PowerShell/PowerShell/releases/download/v7.4.0/powershell_7.4.0-1.deb_amd64.deb
sudo dpkg -i powershell_7.4.0-1.deb_amd64.deb

From the project root directory:

# Generate PDFs for all languages
.\scripts\Create-GuidePDFs.ps1

# Create a new translation template
.\scripts\Create-TranslationTemplate.ps1 -LanguageCode "de" -LanguageName "German"

💡 Note: On macOS and Linux, you may need to use pwsh instead of powershell to run PowerShell 7+.

The project supports multiple environment -Configuration-References:

• -Configuration-Reference: site/hugo.local.yaml
• Features: Debug information, draft content, extended logging

• -Configuration-Reference: site/hugo.yaml
• Features: Optimized build, analytics, production URLs

• -Configuration-Reference: site/hugo.preview.yaml
• Features: Preview-specific settings

# Add Hugo to your PATH or install using package manager
# Windows (Chocolatey)
choco install hugo-extended

# macOS (Homebrew)
brew install hugo

# Linux (Snap)
snap install hugo

# Use a different port
hugo server --port 8080

# Or find and kill the process using port 1313
# Windows
netstat -ano | findstr :1313
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:1313 | xargs kill

# Clear Hugo cache
hugo mod clean

# Update modules
hugo mod get -u

# Clear Hugo cache and restart
hugo mod clean
hugo server -D

ScrumGuide-ExpansionPack/
├── site/                    # Hugo site source
│   ├── content/            # Markdown content files
│   │   ├── _index.md      # Homepage content
│   │   ├── guide/         # Main guide content
│   │   ├── creators/      # Creator profiles
│   │   └── download/      # Download page
│   ├── layouts/           # HTML templates
│   │   ├── _default/      # Default layouts
│   │   ├── guide/         # Guide-specific layouts
│   │   └── partials/      # Reusable components
│   ├── static/            # Static assets (CSS, images, PDFs)
│   ├── data/              # Data files (YAML/JSON)
│   ├── i18n/              # Translation files
│   └── hugo.yaml          # Hugo -Configuration-Reference
├── public/                # Generated site (git-ignored)
├── docs/                  # Project documentation
└── .github/               # GitHub Actions workflows

Now that you have the project running locally, you can:

1. 📝 Learn about Content Management - How to edit and create content
2. 🏗️ Understand the -Architecture-Overview - Project structure and design patterns
3. 🤝 Read -Contributing-to-the-Scrum-Guide-Expansion-Pack Guidelines - How to contribute to the project
4. 🛠️ Explore -Development-Guide Guide - Advanced -Development-Guide topics

If you encounter issues during setup:

1. Check the -Troubleshooting-Guide Guide
2. Search existing GitHub Issues
3. Create a new issue with detailed information about your environment and the problem
4. Join the GitHub Discussions

🎉 Congratulations! You now have the Scrum Guide Expansion Pack running locally. Ready to start -Contributing-to-the-Scrum-Guide-Expansion-Pack?