GitHub Stars Browser

Browse, filter, sort, and group your starred GitHub repos locally, with blog, markdown viewer, and todo tools.

Quick Start

npm start            # Start dev server at http://localhost:3000
npm run build        # Rebuild blog index and settings
npm run test         # Run all tests (176+)
npm run download-deps  # Download external deps locally

Directory Structure

.
+-- app/                     # Page modules
|   +-- home/
|   |   +-- index.html         Home page / sitemap
|   |   +-- css/home.css
|   +-- blog/
|   |   +-- index.html         Blog home
|   |   +-- browse.html        Browse all posts (list/tree view)
|   |   +-- blog.js            Blog listing + post viewer logic
|   |   +-- browse.js          Browse page logic
|   |   +-- css/blog.css
|   |   +-- css/browse.css
|   +-- tools/
|   |   +-- md/                Markdown viewer — render any .md
|   |   |   +-- index.html
|   |   |   +-- viewer.css
|   |   |   +-- controller.js
|   |   +-- todos/
|   |   |   +-- index.html
|   |   |   +-- todos.js
|   |   +-- view-github-stars/ Browse starred repos
|   |   |   +-- index.html
|   |   |   +-- view-github-stars.js
|   |   +-- fetch-github-stars/ Download starred repos as ZIP
|   |   |   +-- index.html
|   |   |   +-- fetch-stars.js  Fetch logic (moved from inline)
|   |   |   +-- cli.js
|   |   +-- css/                Shared tool CSS
|   |       +-- stars.css
|   |       +-- fetch-stars.css
|   |       +-- todos.css
|   +-- settings/
|   |   +-- index.html         App-wide settings
|   |   +-- settings.js
|   |   +-- css/settings.css
+-- common/                  # Shared styles and scripts
|   +-- styles.css            Shared page-level CSS
|   +-- css/
|   |   +-- main.css          Entry point (imports all partials)
|   |   +-- layout/           Page width and column layout variants
|   |   +-- site-styles/      Navbar, footer, TOC, forms, etc.
|   |   +-- markdown/         Markdown rendering styles
|   |   +-- features/         Feature-specific styles (badges)
|   |   +-- README.md
|   +-- js/
|   |   +-- settings-loader.js  Fetches settings, dispatches event
|   |   +-- theme-applier.js    Applies theme, nav, footer, layout
|   |   +-- site-meta.js        Shared meta tag handler
|   |   +-- backtotop.js        Back-to-top button
|   |   +-- render-markdown.js  Markdown engine
|   |   +-- dependencies.js     CDN/local dependency loader
|   |   +-- README.md
|   +-- themes/               Theme CSS files (default, ocean, forest, space)
|       +-- README.md
+-- data/                   Settings, blog posts, star data, READMEs
|   +-- README.md
+-- dependencies/            Optional local libs (no CDN)
|   +-- README.md
+-- dev-server/              Dev server, build scripts, tests
|   +-- server.js
|   +-- build.js
|   +-- test/
|   +-- README.md
+-- package.json
+-- README.md

Documentation

Start here: Directory Guide — links to all section READMes.

Section	README
Blog	app/blog/README.md
Todos	app/tools/todos/README.md
Markdown Viewer	app/tools/md/README.md
Stars Browser	app/tools/view-github-stars/README.md
Fetch Stars	app/tools/fetch-github-stars/README.md
Settings	app/settings/README.md
Common CSS	common/css/README.md
Common JS	common/js/README.md
Themes	common/themes/README.md
Testing	dev-server/README.md

Pages

Page	Description
app/home/	Home page / sitemap
app/tools/view-github-stars/	Browse starred repos — search, filters, sort, group by language, stats
app/tools/md/	Render any markdown — URL mode, file upload, direct mode
app/tools/fetch-github-stars/	Download starred repos and READMEs as a ZIP
app/blog/	Personal blog — posts, tags, featured, frontmatter editor
app/tools/todos/	Aggregated todos from all blog posts
app/settings/	App-wide settings — blog, todo, markdown, nav, themes

Static Site

This app runs entirely as a static site. No server is required at runtime — all pages are plain HTML, CSS, and JavaScript served directly by any static file host (GitHub Pages, Netlify, S3, nginx, etc.).

The dev server (npm start) is only needed during development for features that require a running server: saving settings, rebuilding the blog index, and editing post frontmatter.

What Requires a Rebuild

The blog index (data/blog-index.json) and settings file (data/app-settings.json) are generated files. A rebuild is needed when:

Trigger	How to rebuild
Adding, removing, or renaming a blog post	npm run build or Rebuild button in settings page
Editing post frontmatter (title, tags, date, draft, featured)	npm run build or Rebuild button
Adding or removing tags from posts	npm run build
Changing blog, todo, or markdown settings	Save button in settings page (writes directly)
Theme color overrides	Saved automatically via settings page

Git Repository Hosting

If hosting on a git-based platform (GitHub Pages, GitLab Pages, etc.), directories that contain a .gitignore file — or are listed in the root .gitignore — will be excluded from the served site.

This affects data directories:

Directory	Status
data/github-stars/	In root .gitignore — excluded from git commits. Data is downloaded via fetch-github-stars/ or the CLI.
data/github-stars/{repo}/	In root .gitignore — excluded. Downloaded alongside star data.
data/github-stars/{repo}/assets/	In root .gitignore — excluded. Downloaded alongside star data.

If you rely solely on the git repository for hosting (no separate data fetch), add these directories to your fetch tool first, then commit them.

Dev Server Routes

Method + Path	Description
POST /api/rebuild	Runs npm run build (used by settings page Rebuild button)
POST /api/save-settings	Writes settings to data/app-settings.json
POST /api/save-post-frontmatter	Edits a blog post's YAML frontmatter

External Dependencies

All CDN resources are loaded from cdnjs.cloudflare.com.

Library	Version	Used By	Purpose
highlight.js	11.9.0	app/tools/md/index.html	Syntax highlighting for fenced code blocks
JSZip	3.10.1	app/tools/fetch-github-stars/index.html	Creating ZIP archives of starred repos

Offline / Self-Hosted

To remove all external CDN calls, download the files and place them under dependencies/. See dependencies/README.md for the setup script and full instructions.

dependencies/
+-- highlight.min.js
+-- styles/
|   +-- highlight.min.css
+-- jszip.min.js

common/js/dependencies.js checks dependencies/ first and falls back to CDN if a file is missing — no HTML changes needed.

Common Architecture

• common/js/settings-loader.js — Fetches data/app-settings.json, stores on window.__appSettings, dispatches settings-loaded event.
• common/js/theme-applier.js — Listens for settings-loaded, applies theme CSS variables, builds navbar and footer, sets layout classes.
• common/js/site-meta.js — Shared site metadata handler (title, description, OG tags).
• common/js/render-markdown.js — Markdown engine (renderMarkdown, renderInline, escapeHtml, etc.). Used by app/tools/md/, app/blog/, and app/tools/todos/.
• common/css/main.css — Modular stylesheet entry point. Imports all partials from common/css/.

Data Files

File	Description
data/app-settings.json	App-wide settings (layout, blog, todo, md, nav, site, theme)
data/githubStarData.json	Starred repos data (in .gitignore)
data/github-stars/{repo}/{repo}.md	Downloaded README per repo (in .gitignore)
data/github-stars/{repo}/assets/	Static assets from READMEs (in .gitignore)
data/blog-index.json	Generated blog manifest
data/home.md	Home page markdown (frontmatter + body)
data/blog/blog.md	Blog home page content