https://github.com/brennanbrown/11ty-gamification
🌱 A blog theme that turn writing into a game. Earn badges for streaks and milestones, watch your activity on a heatmap, and get gentle nudges via Badge Ideas. Built with 11ty and a strong testing culture so you can ship confidently.
https://github.com/brennanbrown/11ty-gamification
11ty 11ty-blog 11ty-starter 11ty-template gamification
Last synced: about 1 month ago
JSON representation
🌱 A blog theme that turn writing into a game. Earn badges for streaks and milestones, watch your activity on a heatmap, and get gentle nudges via Badge Ideas. Built with 11ty and a strong testing culture so you can ship confidently.
- Host: GitHub
- URL: https://github.com/brennanbrown/11ty-gamification
- Owner: brennanbrown
- License: mit
- Created: 2025-08-23T19:19:19.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-08-23T19:37:43.000Z (2 months ago)
- Last Synced: 2025-08-24T07:37:38.439Z (2 months ago)
- Topics: 11ty, 11ty-blog, 11ty-starter, 11ty-template, gamification
- Language: TypeScript
- Homepage: https://11ty-gamification.netlify.app
- Size: 304 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 11ty Gamification Monorepo
The 11ty Gamification Monorepo houses a production-ready blog app (the "11ty Gamification Blog") and supporting packages that turn writing into a game. Earn badges for streaks and milestones, watch your activity on a heatmap, and get gentle nudges via Badge Ideas. Built with Eleventy and a strong testing culture so you can ship confidently.
- Live dev stack: Eleventy (Nunjucks), TypeScript, Node, Vitest, Tailwind (light usage), small utilities.
- Monorepo tooling: npm workspaces.
> Philosophy: make writing feel like play. Clear visuals, accessible defaults, and rigorous tests.
Naming:
- Repository (monorepo): "11ty Gamification Monorepo"
- Blog app (in `apps/site/`): "11ty Gamification Blog"
## ⚡ Quick Start
Prerequisites:
- Node 18+ (LTS recommended)
- npm 9+
Install dependencies:
```bash
npm install
```
Run tests (all workspaces):
```bash
npm test
```
Typecheck and lint:
```bash
npm run typecheck
npm run lint
```
Build note: site builds are invoked per package (see below). Some tests call Eleventy directly.
## 📦 Monorepo Structure
- `apps/site/` — 11ty Gamification Blog (Eleventy + Nunjucks)
- `src/` — Templates, assets, and data builders
- `_data/` — Eleventy data sources (e.g., `activity.js`, `analyzer.js`, `badges.js`)
- `_includes/` — Layout and partials (e.g., `layout.njk`)
- Pages (e.g., `index.njk`, `badges.njk`, `posts.njk`)
- `tests/` — Unit and integration tests for the site
- `_site/` — Build output (generated by Eleventy)
- `packages/content-analyzer/` — Analyzer for post content/word counts
- `src/`, `tests/`
- `packages/site-utils/` — Shared utilities for the site UI and data
- `src/`, `tests/`
- `docs/` — Project documentation
- `testing.md` — Detailed testing guide
Root-level config:
- `package.json` — Workspace scripts: `test`, `test:watch`, `typecheck`, `lint`
- `tsconfig.base.json` — Shared TS config
- `vitest.config.ts` — Test runner configuration
## Scripts
From repository root:
- ⚡️ `npm test` — Run all tests across workspaces (Vitest `--run`)
- 🔁 `npm run test:watch` — Watch mode
- 🔍 `npm run typecheck` — TypeScript typecheck (no emit)
- 🧹 `npm run lint` — ESLint across the repo
Per-package build commands live within `apps/*` and `packages/*` where applicable. Integration tests will run Eleventy builds where needed via `npx eleventy` from the `apps/site/` directory.
## 🧭 Development Workflow
- Make changes within `apps/site/src/` and supporting packages in `packages/*`.
- Add tests alongside the changes. See Testing section.
- Run `npm test` at root to exercise all packages.
- For Eleventy pages and data:
- Keep Nunjucks logic explicit and simple (avoid ternary quirks).
- Prefer `data-*` attributes for test targeting.
Local Eleventy build (optional, for manual inspection):
```bash
npx eleventy
# or from apps/site:
# npx eleventy --input=src --output=_site
```
Open `apps/site/_site/index.html` to view output.
## 🎯 Why 11ty Gamification
- Gamified progress with badges (streak, spirit, word count, behavior)
- Words-based heatmap calendar with refined buckets and legend
- Badge Ideas that unlock dynamically based on your activity
- Fast build, small footprint, simple Nunjucks templates
- Strong tests (integration + unit) and CI coverage gates
## Features Overview
- **Badges**
- Streak tiers: `3, 5, 10, 30, 100, 200, 365`
- Spirit (total active days): same thresholds as streak
- Word count tiers: `750, 5k, 10k, 50k, 100k, 250k, 500k, 750k, 1M`
- Behavior badges: Early Bird (before 09:00 UTC today), Night Owl (≥22:00 UTC today)
- Implementation: `apps/site/src/_data/badges.js` and `apps/site/src/index.njk`
- **Heatmap Calendar**
- Responsive sizing via CSS var `--cell-size`
- Data from `apps/site/src/_data/activity.js`
- Words-based shading thresholds and customization: see `docs/heatmap.md`
- **Search, Tags, Posts**
- Tag colors, pills, and helpers under `packages/site-utils/`
- Analyzer computes word totals in `packages/content-analyzer/`
## ✅ Testing
Extensive tests cover data builders, UI rendering, and integration builds.
- Start here: `docs/testing.md`
- Running tests, filtering, coverage
- Integration test patterns with Eleventy
- Adding new tests and conventions
Project policy: every implementation change should include unit/integration tests.
Related docs:
- Heatmap thresholds and customization: `docs/heatmap.md`
Key tests to know:
- Heatmap legend and buckets: `apps/site/tests/heatmapLegend.integration.test.ts`
- Badge Ideas logic and rendering: `apps/site/tests/badgeIdeas.integration.test.ts`
- Dashboard snapshots: `apps/site/tests/dashboardSnapshot.test.ts`
Related docs:
- Heatmap thresholds and customization: `docs/heatmap.md`
### Snapshot guidance
- Dynamic HTML (dates, counts, generated markup like the dashboard heatmap/ideas) is prone to frequent diffs. Prefer structural assertions over snapshots for these areas to reduce flakiness.
- Example: `apps/site/tests/dashboardSnapshot.test.ts` asserts presence of the Badge Ideas section and Heatmap legend with regex-based checks instead of storing a snapshot.
## 🔄 CI
GitHub Actions workflow at `.github/workflows/ci.yml`:
- Install, typecheck, lint, and `npm test` on pushes and PRs.
## 🚀 Deployment
### Netlify (recommended)
Production build settings (already provided in `netlify.toml`):
- Base directory: `apps/site`
- Build command: `npm run build`
- Publish directory: `apps/site/_site`
PR Deploy Previews via GitHub Actions require repository secrets:
- `NETLIFY_SITE_ID` — your site ID from Netlify
- `NETLIFY_AUTH_TOKEN` — a personal access token
Add them under GitHub → Settings → Secrets and variables → Actions. The workflow `.github/workflows/ci.yml` will publish draft previews for pull requests when these are present.
### Manual build
```
npm run build
# Open apps/site/_site/index.html
```
## 🙏 Attribution
This project takes heavy inspiration from 750words and Buster Benson. If you like this approach to daily writing, consider supporting their original work:
- 750words: https://750words.com
- Buster Benson: https://busterbenson.com
## 🤝 Contributing
- Fork the repo and create feature branches.
- Keep PRs focused and include tests and brief documentation updates.
- Run all tests: `npm test`
- Type-check: `npm run typecheck`
- Lint: `npm run lint`
## License
- Code: MIT — see `LICENSE`
- Content: CC BY-NC-SA 4.0 — see https://creativecommons.org/licenses/by-nc-sa/4.0/