Forkable, HTML-first knowledge repository — a "public Obsidian." One page, one vault: drop .md/.docx/.pptx/.txt/.pdf/.xlsx/.csv/.jpg/.jpeg/.png files into vault/, they're rendered client-side, restyled into one consistent look. Nothing here depends on a closed platform or a paid CMS.
- Create the GitHub repo (see "Push this" below) — or publish directly from GitHub Desktop.
- In the repo, go to Settings → Pages → Source, set it to GitHub Actions. This is the only manual step. Without it the deploy job has nowhere to publish to.
- Drop a
.md,.docx,.pptx,.txt,.pdf,.xlsx,.csv,.jpg/.jpeg, or.pngfile anywhere undervault/(create folders freely — the sidebar mirrors whatever tree you build; files at the top level ofvault/show up at the top level of the sidebar, no wrapper folder needed). - Commit and push (or let GitHub Desktop do it).
Push triggers everything else: CI regenerates vault/manifest.json (the index the sidebar reads, since GitHub Pages can't list directories on its own) and deploys the site. No template to copy, no link to add anywhere by hand.
index.html is the vault viewer — the whole site is one page. It renders .md/.docx/.pptx/.txt/.pdf/.xlsx/.csv/.jpg/.jpeg/.png client-side, sanitized (DOMPurify) and restyled into Forage's own look rather than each format's native appearance. It also supports a private mode: drop any file onto the empty viewer state, or click "start a new note," to read/write in your browser without it touching the repo or being visible to anyone else. Per-file reading notes (the "Sidenote" panel — a small rich-text editor: bold/italic/underline/strikethrough plus a highlighter) are private too — stored only in your own browser's localStorage, never committed or shared. The navigation sidebar, viewer, and sidenote panel are all independently resizable by dragging the divider between them.
Export a file as .html, .pdf (browser print), .md (original source, .md/.txt only), .docx, .json (.md/.docx only — .docx/.json need real document structure, which plain text/slide decks don't have), .txt, .csv (only when there's a table on screen), or .jpeg from each pane's export menu — options that wouldn't produce anything meaningful for the open file (e.g. CSV export with no table, or Markdown-source export for a .docx) are greyed out rather than silently doing nothing.
forage-library/
├── index.html the vault viewer — the whole site
├── sw.js opt-in offline-mode service worker (site root — see its own header comment for why)
├── vault/
│ ├── manifest.json generated by scripts/generate-manifest.mjs on every push
│ └── ... your folders and files
├── assets/
│ ├── css/forage.css shared stylesheet — palette (7 themes), ribbon, vault layout, print rules
│ ├── js/
│ │ ├── ribbon.js ribbon interactions incl. the theme popover
│ │ ├── offline.js wires the "make available offline" button
│ │ ├── visitor-counter.js
│ │ └── vault/ the client-side vault viewer (rendering, sidebar, split view, sidenotes, export)
│ └── images/
├── scripts/
│ └── generate-manifest.mjs walks vault/ and writes vault/manifest.json
└── .github/workflows/publish.yml CI: test → generate manifest → deploy Pages
Title flush left; on the right, a theme popover, an offline-mode toggle, and a kebab menu (Open in split). Per-file actions — Sidenote and the export menu — live in each pane's own header instead.
Seven themes — Sakura, Cherry, Forest Brew, Tea Mist, Blueberry, Kokoblu, Dubai — picked from a popover (not a toggle; ported as-is from github.com/forageopen/Noted). Cherry is the default for a first-time visitor. The choice persists in localStorage (forage-theme) across visits. A small inline script in <head>, before the stylesheet loads, applies the saved theme immediately so there's no flash of the wrong one.
Tokens are CSS custom properties in assets/css/forage.css (:root = Sakura, html[data-theme="..."] = each other theme) — mapped onto this file's own token names (--bg, --text, --teal, --ribbon-*, etc.) rather than Noted's --ds-* naming, so every existing component rule works unmodified. Not the Forage brand-skill tokens — that's parked for now per your instruction. The scrollbar color follows whichever theme is active automatically, since it's driven by the same tokens.
Opt-in — nothing registers automatically. Click the cloud icon in the ribbon to cache the app shell (this repo's own HTML/CSS/JS plus the CDN rendering libraries) via a service worker (sw.js, at the site root — load-bearing, not stylistic, since GitHub Pages doesn't send the header that would let a subdirectory-hosted worker control the whole site). Individual vault files you haven't already opened aren't precached, since the vault can grow arbitrarily.
CC BY-NC-SA 4.0 — see LICENSE. Standing decision now: every Forage repo under github.com/forageopen uses this license, full stop — not MIT. MIT lets anyone fork and resell the content commercially, which cuts against treating it as monetizable IP.
Fork it, change the palette in assets/css/forage.css, delete the sample vault entry (vault/generative-ai-documentation-process.md), start writing. No build step, no dependency beyond Node for the test suite.
If not publishing directly from GitHub Desktop:
cd forage-library
git remote add origin https://github.com/forageopen/forage-library.git
git branch -M main
git push -u origin mainThen do the Pages source step above.