Builder Season Playbook

Hello World

2026-04-29T00:00:00Z

I registered for the hackathon today and created the repo and made an annoucement post on X

Cool day ... and I got my progress log working ... I think.

It works but I still need to clean up some stuff. Cheers!

todo:

make blog-menu work in the most simple way - change to npm
make npm scripts to acces the blog / logging

The Web is on

2026-05-01T00:00:00Z

So today I was able to get the website going with this rogress log and an activity dashboard that pulls things from Discord and you know creates an 11T site that's able to be published on Github pages Feel like it was pretty good for Friday afternoon Have a great weekend!

Some Todo: Add Twitter profile pics, cutoff long commit messages, save the data from the API locally to cutdown on hitting the API limits, something with collecting and verifying the Twitter update posts

X search semi automated

2026-05-05T00:00:00Z

Working on shifting to Python and to a simple data model Moving away from Python to node Codex says:

• The activity pipeline is now Node-based.

  I replaced web/scripts/generate-activity.sh:1 with web/scripts/generate-activity.mjs:1 and updated web/
  package.json:1 so npm run build:data now runs node ./scripts/generate-activity.mjs. The new script keeps the
  same output shape in web/src/_data/activity.json, but the date math, GitHub requests, pagination, and JSON
  shaping all live in one Node module now.

Questions

What is normalization? When to use Bash, Python, or Node? is there a way to have a "don't hit the API" flag? The problem of builders starting in different weeks. Could each builder have a "start week" attribute?

Reference

xSearch = { adminWeek1Start, adminDurationWeeks, builderUpdateDurationWeeks, defaultBuilderWeek1End, weeklyUpdateHashtags, weeklyUpdateMention, configError, currentAdminWeekIndex, weeks: [ { index, startDate, endDateExclusive, endDateInclusive, label, dateRangeLabel, searchUrl } ], builders: [ { id, name, xHandle, firstUpdateWeekStart, firstUpdateWeekEnd, firstAdminWeekIndex, finalPresentationWeekEnd, searchUrl, weeks: [ { index, startDate, endDateExclusive, builderWeekIndex, builderWeekLabel, label, dateRangeLabel, searchUrl } ] } ] }

activity = { generatedAt, weekStart, weekEnd, builders: [ { id, name, lastActivityAt, commitsThisWeek, recentCommits: [ { repo, message, url, committedAt } ], error } ] }

builders = [ { id, name, github, x, xRequiredHashtags, xRequiredMention, xIgnore, projectName, projectUrl, repoUrl, pies, notes } ]

Bash Bash? move from Bash to Python

2026-05-05T00:00:00Z

I wanted to make sure I was using the right tooling and I think Python fits here. I'm using a script to take yml data - that I manually input and that outputs JSON for the 11ty to build the frontend... but why? Why not just use the yaml? Im pretty sure 11ty can use yml as well as JSON.

I think it's part of the iterative process to go back and rebuild when I 'see' it better. And, it underlines the data model first building method that I've seen some folks use. ... and that's what I'll do tomorrow.

PS: I'm pleased with the current Piece of pie hackathon. we closed the registration and have over 20 builders - which meets our goal. And, I'm happy with creating this repo to 'productize' the hackathon and make it a replicable safe space for builders of tomorrow. (yeah, I really think like that)

Codex says:

Implemented the Python migration. The builder normalization logic now lives in web/scripts/builders_json.py:1, with comments at the
  same intent-level as the shell scripts, and the old builders-json.sh entrypoint has been removed. Callers now invoke python3
  directly from web/package.json:7, web/scripts/generate-activity.sh:25, and web/scripts/generate-x-posts.sh:13.

  I also added the minimal Python dependency file at web/requirements.txt:1, updated both GitHub Actions workflows to install Python
  and PyYAML before builds (.github/workflows/update-activity.yml:30, .github/workflows/deploy.yml:37), and refreshed the docs in
  README.md:90 and web/README.md:15 to reflect the new runtime and the fact that the X pipeline still uses Ruby for now.

  Verification: python3 web/scripts/builders_json.py passed, and npm run build:data:x passed end-to-end. I did not fully verify npm
  run build:data because that path calls the live GitHub API. One generated file changed in-repo: web/src/_data/builders.json:1. Its
  content is equivalent, but empty arrays are now rendered as [] instead of Ruby’s multiline empty-array formatting.

updating the repos.yml

2026-05-06T00:00:00Z

Just updating the repos.yml with the "source of truth" spreadsheet that Harsha and I work with as admin ... and yes, I did it by hand, check it line by line and then ask copilot to verify it.

I'm learning so many little things by working on this project. Like .yml files and 11ty global data. One technique is to search Github for how others are using it and asking the AI to explain stuff.

The tech stack for this project

2026-05-06T00:00:00Z

Here's the tech stack for this repo:

Core:

Eleventy (11ty) v3.1.2 — Static site generator
Nunjucks — Template engine (.njk files)
Node.js — Runtime (ES modules)

Data & Config:

YAML (js-yaml v4.1.1) — Configuration files (repos.yml, event.yml)
GitHub API — Source of commit activity data
JSON — Data interchange (activity.json, builders.json, xSearch results)

Plugins:

@11ty/eleventy-plugin-rss v2.0.4 — Atom feed generation

Build & Scripts:

npm scripts — Task runner
Node.js ES modules — Standalone scripts for data generation (.mjs files)

Architecture summary:

Config layer → repos.yml (manual registry) + event.yml (event timing)
Data generation → generate-activity.mjs fetches GitHub API, outputs activity.json
Data aggregation → _data files (builders.js, activity.json, xSearch.js) provide global template data
Templates → Nunjucks + custom Eleventy filters (defined in eleventy.config.js)
Output → Static HTML in _site

The workflow is: YAML config → GitHub API → JSON snapshot → Nunjucks templates → Static site.

No framework cruft (React, Vue, etc.) — pure static generation optimized for content and dashboards.

writing a newsletter and updating the weeks

2026-05-08T00:00:00Z

Hello Happy Hackers

I'm not sure why we ended the weeks on a Sunday. I suppose it was to highlight the 'deadline' or 'due date' aspect. It could just as easily been ending on Friday, due on Friday. In future hachathons, this will be configurable.

We addressed the Admin Week and Builder week. The Admin weeks start when registration begins and the buider weeks start when registration closes. ... hmmm, maybe next time we use the NASA model of Time Minus and Plus. Weeks before registration closes (LIFTOFF) are Minus weeks and after are plus weeks or just weeks.

Anyway - happy Friday

and here is what Codex says:

Implemented the week-model change across config, data generation, dashboard UI, and docs.

  The core change is in /home/nsl/ad-ipsum/builder-season-playbook/config/event.yml:18, scripts/event.mjs:18, and src/
  _data/xSearch.js:1. Admin week 1 is now anchored to 2026-04-13 through 2026-04-19, the admin calendar runs for 14 weeks,
  builder updates run for 12 consecutive weeks, and the default builder Week 1 is the week ending 2026-05-03. Builder
  timing is now computed separately from admin week numbering, so a builder’s Week 1 can correctly map to Admin Week 3 and
  their final presentation week can land on 2026-07-19.

  The dashboard and builder pages now explain that distinction instead of hiding it. src/dashboard/index.njk:16 keeps
  admin week labels as the canonical labels, adds builder Week 1 and final presentation columns, and clarifies that the
  GitHub activity section uses the current UTC week. src/builders/builder.njk:45 shows each builder’s Week 1 update
  timing, admin-week offset, and final presentation week. I also updated README.md:30, /home/nsl/ad-ipsum/builder-season-
  playbook/config/repos.yml:1, and the internal reference post at src/posts/2026-05-05-x-search-semi-automated.md:28.

  I used an event-level default for all current builders rather than writing the same first_update_week_end into every
  builder entry. Individual builders can now override that in config/repos.yml when needed.

  Verification: ./node_modules/.bin/eleventy completed successfully, and the generated data confirms Week 1 = Apr 13 to
  Apr 19, Week 2 ends 2026-04-26, default builder Week 1 ends 2026-05-03, and the computed final presentation week ends
  2026-07-19.

Builder facepile and post tools

2026-05-12T00:00:00Z

Today I made two related improvements to the Builder Season Playbook: a new builder facepile on the homepage and a smoother post-writing workflow for future updates.

Builder Facepile

The homepage now includes a GitHub-profile-image facepile built from the existing normalized builder registry. The data still flows from config/repos.yml, optional project.yml overlays, and then through the shared builders array that Eleventy already consumes.

I added a small normalization step so each builder exposes githubProfileUrl, githubAvatarUrl, displayName, and builderPageUrl. The avatar URLs use the stable GitHub pattern https://avatars.githubusercontent.com/{username}?s=80, and the landing page renders those images with accessible markup, explicit dimensions, and lazy loading.

The section fits the site’s current warm editorial look: overlapping circular avatars, subtle hover and focus states, and wrapping that still works on mobile.

Post Authoring

I also updated the posting workflow so new posts can include an explicit author line without rewriting the older archive by hand. The shell scaffolds now default to author: "Newman", while the post templates render Author: Newman when a post does not define an author.

For agent-authored posts, there is now a dedicated create-post routine and repo-local plugin bundle. The script can generate a markdown file, create the matching image directory, and prefill a short summary body. That gives us a cleaner path for turning work sessions into publishable updates without having to reconstruct the front matter every time.

Verification

I ran the local Eleventy build after these changes. The homepage facepile rendered, existing posts displayed the new author line correctly, and the post-creation dry run produced the expected file path, image directory, and front matter.

That should make the site feel a little more personal on the front page and a little easier to maintain behind the scenes.