The Problem
Tracking interesting open-source repositories is fragmented. Starring repos on GitHub gives you a flat list with no context, and manual curation doesn't scale. This project solves that by generating a curated, self-hosted showcase site with posts, related-content links, and an RSS feed — automatically.
What This Does
repoposts is a Jekyll static site stored under docs/ that publishes curated posts about notable GitHub repositories. Each post in docs/posts/ follows a YYYY-MM-DD-owner-repo.md naming convention and includes a screenshot and description. The site uses the Minimal theme with a custom layout override in docs/layouts/default.html.
The pipeline is automation-heavy. GitHub Actions workflows handle the recurring work: generate-related-min.yml computes related posts using embeddings stored in docs/data/embeddings.npz and writes results to docs/data/related.json. A separate workflow (rss-smoke.yml) validates the feed. The site deploys via GitHub Pages on push to main.
How To Use It
Setup: Clone the repo and run the Jekyll site locally with bundle exec jekyll serve from the docs/ directory. The docs/Gemfile.lock pins dependencies; the Makefile may have convenience targets, though the README doesn't document them.
Configuration: Site settings live in docs/config.yml. No environment variables are required for local development. For CI, the workflows in .github/workflows/ handle deployment and data generation automatically.
Running it: Push to main to trigger the Pages deploy. The site is live at https://tom-doerr.github.io/repoposts/. The related-data workflow runs every 30 minutes on a schedule. To add content, create a new post in docs/posts/ following the existing naming pattern.
Local development
cd docs bundle install bundle exec jekyll serve
Real-World Use
A team maintaining an internal list of useful open-source tools could fork this repo and replace the posts with their own curated set. The embeddings-based related-posts feature gives readers a way to discover similar tools without manual tagging. The RSS feed (feed.xml) lets subscribers track new additions. The automated workflows mean the site stays current with minimal manual intervention.
Code Health & Issues
The repo is structurally sound: it has CI, a license, and a lockfile. The workflows are well-named and cover the core operations (build, related-data generation, RSS validation, image compression). Med - Embedded binary data in git - docs/_data/embeddings.npz is a NumPy archive committed to the repo. This bloats the repository and creates merge conflicts on regeneration. It should be generated at build time or stored in a separate artifact store. Low - No test coverage for the data pipeline - The workflows run, but there's only one test file. The embedding computation and related-post generation have no unit tests, so regressions would surface only at runtime. Low - Hardcoded paths and schedules - The 30-minute cron in generate-related-min.yml is reasonable, but the embedding refresh strategy (compute only missing neighbors) could fail silently if the data format changes. Low - No contribution path for content - The README explicitly rejects repo suggestions via Issues/PRs. This is intentional, but it means the content quality depends entirely on the maintainer's curation process.
The Bottom Line
A well-executed, automated content pipeline for a curated GitHub showcase. The embeddings-based related-posts feature is a genuine differentiator. It's not a general-purpose tool — it's a specific solution for one maintainer's workflow. Fork it if you want a similar setup for your own curated list, but expect to adapt the data pipeline to your needs.