|
| 1 | +# Copilot Instructions for Killed by Scrum.org |
| 2 | + |
| 3 | +This document contains important instructions for GitHub Copilot when working with this project. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a Hugo-based static website for the "Killed by Scrum.org" project, which tracks obituaries of discontinued Scrum.org initiatives, tools, and programmes. |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +### Development Server |
| 12 | + |
| 13 | +To run the Hugo development server: |
| 14 | + |
| 15 | +```powershell |
| 16 | +hugo serve --source site --config hugo.yaml,hugo.local.yaml |
| 17 | +``` |
| 18 | + |
| 19 | +### Production Build |
| 20 | + |
| 21 | +To build the site for production: |
| 22 | + |
| 23 | +```powershell |
| 24 | +hugo --source site --config hugo.yaml |
| 25 | +``` |
| 26 | + |
| 27 | +## Project Structure |
| 28 | + |
| 29 | +- `site/` - Hugo source code |
| 30 | + - `hugo.yaml` - Main Hugo configuration |
| 31 | + - `hugo.local.yaml` - Local development configuration (if exists) |
| 32 | + - `content/` - Markdown content files |
| 33 | + - `data/register.json` - Obituary data |
| 34 | + - `layouts/` - Hugo templates |
| 35 | + - `static/` - Static assets |
| 36 | +- `public/` - Generated Hugo output (after build) |
| 37 | +- `.powershell/` - PowerShell automation scripts |
| 38 | + |
| 39 | +## Key Features |
| 40 | + |
| 41 | +### GitHub Discussions Integration |
| 42 | + |
| 43 | +- **Automated Discussion Creation**: PowerShell script `.powershell/Create-GitHubDiscussions.ps1` creates GitHub discussions |
| 44 | +- **Data Integration**: Script adds `discussionId` and `discussionUrl` fields to obituaries in `site/data/register.json` |
| 45 | +- **Template Integration**: Hugo templates read these fields directly to display discussion buttons |
| 46 | +- **Category Management**: Creates discussions in the "Obituary" category |
| 47 | +- **Idempotent Operation**: Safe to run multiple times, skips existing discussions |
| 48 | + |
| 49 | +### Configuration |
| 50 | + |
| 51 | +- GitHub repository is configured in `site.Params.githubRepo` (hugo.yaml) |
| 52 | +- Currently set to: `https://github.com/MrHinsh/killed-by-scrumorg` |
| 53 | + |
| 54 | +## Development Notes |
| 55 | + |
| 56 | +### GitHub Discussions Workflow |
| 57 | + |
| 58 | +**Prerequisites:** |
| 59 | + |
| 60 | +1. Set `HUGO_GITHUB_TOKEN` environment variable with a GitHub Personal Access Token |
| 61 | +2. Token must have `public_repo` or `repo` scope (not just `write:discussion`) |
| 62 | +3. GitHub Discussions must be enabled on the repository |
| 63 | +4. "Obituary" category must exist in GitHub Discussions |
| 64 | + |
| 65 | +**Running the Script:** |
| 66 | + |
| 67 | +```powershell |
| 68 | +.\.powershell\Create-GitHubDiscussions.ps1 |
| 69 | +``` |
| 70 | + |
| 71 | +**How it works:** |
| 72 | + |
| 73 | +1. The script scans `site/data/register.json` for obituaries without `discussionId` fields |
| 74 | +2. Creates GitHub discussions for those obituaries in the "Obituary" category |
| 75 | +3. Updates the JSON file with `discussionId` and `discussionUrl` fields |
| 76 | +4. Hugo templates automatically display discussion buttons for linked obituaries |
| 77 | +5. Script is idempotent - skips obituaries that already have discussion IDs |
| 78 | + |
| 79 | +**Integration with Hugo:** |
| 80 | + |
| 81 | +- Hugo templates check for `{{ if .discussionUrl }}` to conditionally show discussion buttons |
| 82 | +- No Hugo functions or build-time API calls required |
| 83 | +- All data is pre-populated in the JSON file by the PowerShell script |
| 84 | + |
| 85 | +### Data Format |
| 86 | + |
| 87 | +- Obituaries are stored in `site/data/register.json` |
| 88 | +- Each obituary should have at least a `title`, `description`, `birth_date`, and `death_date` field |
| 89 | +- Optional fields: `type`, `url` |
| 90 | +- After running the PowerShell script, obituaries will have `discussionId` and `discussionUrl` fields |
| 91 | + |
| 92 | +## Common Tasks |
| 93 | + |
| 94 | +### Adding New Obituaries |
| 95 | + |
| 96 | +1. Edit `site/data/register.json` |
| 97 | +2. Add new obituary object with required fields (`title`, `description`, `birth_date`, `death_date`) |
| 98 | +3. Run the PowerShell script to create discussions: `.\.powershell\Create-GitHubDiscussions.ps1` |
| 99 | +4. Build the site with Hugo |
| 100 | + |
| 101 | +### Creating GitHub Discussions |
| 102 | + |
| 103 | +The PowerShell script automatically handles this: |
| 104 | + |
| 105 | +```powershell |
| 106 | +# Using environment variable (recommended) |
| 107 | +.\.powershell\Create-GitHubDiscussions.ps1 |
| 108 | +
|
| 109 | +# Or passing token directly |
| 110 | +.\.powershell\Create-GitHubDiscussions.ps1 -GitHubToken "your-github-token" |
| 111 | +``` |
| 112 | + |
| 113 | +### Testing Changes |
| 114 | + |
| 115 | +1. Use `hugo serve --source site --config hugo.yaml,hugo.local.yaml` for live reload |
| 116 | +2. Access the site at `http://localhost:1313` |
| 117 | + |
| 118 | +### Deployment |
| 119 | + |
| 120 | +- The site uses Azure Static Web Apps |
| 121 | +- Configuration files: `staticwebapp.config.*.json` |
| 122 | +- Different configs for different environments (production, preview, canary) |
| 123 | + |
| 124 | +## File Locations |
| 125 | + |
| 126 | +### Hugo Templates |
| 127 | + |
| 128 | +- Main page: `site/layouts/index.html` |
| 129 | +- Base template: `site/layouts/_default/baseof.html` |
| 130 | +- **Note**: No discussion function needed - discussions are handled via data fields |
| 131 | + |
| 132 | +### Styling |
| 133 | + |
| 134 | +- CSS: `site/static/css/style.css` |
| 135 | +- Images: `site/static/images/` |
| 136 | + |
| 137 | +### Content |
| 138 | + |
| 139 | +- Homepage: `site/content/_index.md` |
| 140 | +- Data: `site/data/register.json` |
| 141 | + |
| 142 | +### PowerShell Scripts |
| 143 | + |
| 144 | +- GitHub Discussions: `.powershell/Create-GitHubDiscussions.ps1` |
| 145 | + |
| 146 | +## Important Notes |
| 147 | + |
| 148 | +- Always use the correct Hugo command with `--source site` flag |
| 149 | +- The project has multiple configuration files - use both `hugo.yaml` and `hugo.local.yaml` for development |
| 150 | +- GitHub discussions are created via PowerShell script, not during Hugo build |
| 151 | +- The site is statically generated - discussion data is pre-populated in JSON |
| 152 | +- PowerShell script is idempotent and safe to run multiple times |
| 153 | +- **Token Requirements**: GitHub token needs `public_repo` or `repo` scope, not just `write:discussion` |
| 154 | +- **No backup files**: PowerShell script doesn't create backup files to avoid Hugo build conflicts |
0 commit comments