This repository is the hub. It holds the website at glassbox.how, the studio that turns a box into Reels, Shorts, a YouTube video, a carousel and captions, and the publish kit that schedules those through Buffer. Each box lives in its own repository.
| |
|---|
| |
| Home. Today's box opens from a black box into glass; search anything with /. | Explainer. The question, the 40-second video, six plain-language beats, key terms, the code. |
| |
| History. Every box's past as a visual story: eras, a timeline of moments, charts, people, places and sources. | Concepts A–Z. Every term across every box, each linked to where you can see it working. |
Boxes so far
The live list is the shelf, built automatically from every public repo in the org tagged glassbox-box.
How the pieces fit
github.com/glassboxhow glassbox.how
├─ glassboxhow.github.io (this repo) ──► / home: today's box, the shelf, calendar
│ GitHub Actions builds it from ──► /e/<slug>/ explainer page for each box
│ every box's glassbox.json ──► /concepts/ every term, A to Z
│ and history.json ──► /e/<slug>/history/ that box's history, told visually
│ ──► /history/ every history on one timeline
│ ──► /privacy/ /terms/
│ ──► /studio/ recording + publish kit
├─ cameraclear (No. 001) ──► /cameraclear/ the box itself
│ glassbox.json the manifest /cameraclear/glassbox/reel.mp4, slides, thumbnail…
│ history.json its history
│ glassbox/ studio output
└─ <tomorrow's box> (No. 002) ──► /<slug>/
- Every box is its own public repo with GitHub Pages turned on. GitHub serves an org's project sites under the org site's custom domain, so
glassboxhow/cameraclear appears at glassbox.how/cameraclear/ with no proxy and no bill.
- The hub finds boxes by topic. Any public repo in the org tagged
glassbox-box with a glassbox.json joins the shelf. The build runs every two hours, on every push, or straight away when a box's notify-hub workflow pings it.
- Each box hosts its own media. The studio writes the videos and images into the box's
glassbox/ folder, which keeps every repo far below GitHub's size limits. It also gives Buffer the public media URLs it needs.
- Measured in the open. Visits are counted with Google Analytics and bots detected with ClickTrust. Both load from one generated file,
/assets/analytics.js, and nothing else is allowed. Fonts and libraries are self-hosted, and every page's Content Security Policy only permits our domain and those two services. There is no database and no account system. See Privacy.
- Zero npm dependencies. The build, dev server and poster are plain Node 20. The site is plain HTML, CSS and JavaScript.
The daily loop
npm run new -- <slug> "How does X work?" --field physics # scaffold ../<slug> as the next box
npm run dev # http://localhost:5210
- Build the model in
../<slug>/app.js, fill in glassbox.json, and write the storyboard (window.glassbox.director). The contract is in docs/CONTRACT.md.
- Research the history in
../<slug>/history.json: eras, 20–50 sourced moments, people, a number series or two. The guide is in docs/HISTORY.md.
- Record at
http://localhost:5210/studio/?box=<slug>. You get a 16:9 video, a 9:16 Reel/Short, 10 carousel slides, a thumbnail, a share card and a clean still. It encodes in the browser (WebCodecs), faster than real time, with a generated soundtrack.
Record history makes a “history in 10 moments” Reel/Short and carousel from history.json.
- Words: edit the drafted captions for Instagram, YouTube, X and LinkedIn.
- Ship: pick a time → Save to repo → Dry run → Ship it. That commits
glassbox/, pushes it, waits for Pages to serve the files, then schedules every post in Buffer.
- First time only for a box:
scripts/github-setup.sh <slug> creates the public repo and fills in its description, homepage, topics, README, licences and Pages.
What gets posted
| Target | Asset | Copy |
|---|
| Instagram Reel | reel.mp4 (1080×1920) | Instagram caption |
| Instagram carousel (+4 h) | slide-1…10.jpg (1080×1350) | carousel caption |
| YouTube Short | reel.mp4 | Short title and description |
| YouTube video | video.mp4 (1920×1080) | long title and description |
| LinkedIn, X | video.mp4 | LinkedIn / X copy |
| Threads, TikTok | reel.mp4 | LinkedIn copy |
| Instagram / YouTube history (off by default) | history-reel.mp4, history-slide-*.jpg | history captions |
A target is skipped when no matching channel is connected in Buffer. Change the list in glassbox.config.json.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
