Imagine you have a giant digital toy box. Inside, you keep the cool things you've built, the stories you've written, and a diary of all the interesting things you've learned. Fezcodex is that toy box. It is a special website that works like a personal museum on the internet. It is not just a boring page; it has moving parts, secret "Easter eggs," and little mini-apps like a sound mixer and a knowledge graph.
- Digital Garden: A space where blog posts and "logs" (mini-diaries about books, movies, or games) grow.
- Knowledge Graph: A 3D interactive visualization of how all content on the site is interconnected.
- Project Archives: A showcase of all the coding experiments and software I've built.
- Mini-Apps: Built-in tools like an Atmosphere Mixer, Cloud Music Player, Typing Tester, and a digital Rotary Phone.
- Visual Magic: Change how the whole site looks using the "Visual Matrix"—make it look like an old computer (CRT), a blueprint, or even a comic book.
- Achievements: Just like a video game, you get little trophies for exploring the site and finding hidden things.
- Frontend: React 19, Tailwind CSS, and Framer Motion for smooth animations.
- 3D & Graphics: Three.js and react-force-graph-3d for the knowledge graph.
- Content: Markdown and PIML (Plain Old Markup Language) for structured content.
- Build Tools: Vite + Vike for the SPA build and one HTML shell per route; GitHub Actions builds and deploys to GitHub Pages. An optional Puppeteer crawler can prerender page content (
npm run prod:full). - Persistence: Local Storage for settings, achievements, and persistent state.
src/app/: Domain logic, core features, and views (Achievements, OS, Command Palette, etc.).src/components/: Reusable UI components (Buttons, Modals, Cards).src/context/: Global state management (Visual Settings, Toast, Animation).public/: The "pantry" where all actual content (PIML files, text, images, sounds) is stored.scripts/: Helper programs for generating RSS, sitemaps, and wallpapers.
Make sure you have Node.js installed on your computer.
git clone https://github.com/fezcode/fezcode.github.io.git
cd fezcode.github.ionpm installnpm startThis will open the site at http://localhost:5190 (the dev server port set in vite.config.mjs; if that port is busy, Vite falls back to the next free one — check the terminal output).
This project uses BrowserRouter for clean URLs. To support this on static hosts like GitHub Pages, the build writes a real index.html for every route:
- Vite + Vike produces the JS bundles and writes one empty-shell
index.htmlper route listed inpages/routes.jsplus every dynamic route discovered bypages/discoverRoutes.js(blog posts, series episodes, log entries, story book pages, discovery entries, tag pages — ~1,100 routes total). Each shell gets its own title, description and OG image fromscripts/inject-meta.mjsandscripts/generate-og-images.mjs, so link previews work without any further step. scripts/prerender-crawl.mjs(optional; full builds only) spins up a Vite preview server, loads each shell in headless Chromium, and replaces the empty#react-rootwith the rendered HTML. The browser discards that snapshot and renders fresh once the bundle runs, and the snapshot always shows the default theme, so its only real benefit is text for crawlers that don't run JavaScript. It takes ~7 minutes, sonpm run prodskips it; usenpm run prod:fullwhen you want it. Skipped routes fall back to SPA rendering at runtime — not a build failure.
| Command | What it does | When to use |
|---|---|---|
npm run build |
Vite build + post-build + full prerender crawl + OG images + meta | What npm run prod:full uses. Produces a fully prerendered dist/client/. |
npm run build:lite |
Pregenerate + Vite build + OG images + per-page meta, no crawl | What npm run prod uses. Pages render in the browser; link previews are unchanged. |
npm run build:fast |
Vite build + post-build only (no crawl, no OG images or meta) | Fast iteration on components; skip the ~7 min crawler. |
npm run build:retry |
Full crawl, then re-attempts any routes that missed the render gate | Use when the default build reports many skipped routes (flaky JS/fetch under load). |
Tune the crawler via env vars: PRERENDER_CONCURRENCY=6 (default 6; use 3 if the crawl stalls), PRERENDER_RETRY=1 (same as --retry).
The site is built and published by GitHub Actions (.github/workflows/deploy.yml), using the official Pages actions: the repo's Pages source is GitHub Actions, not a branch.
npm run prod # lint + git push; the push to main builds (build:lite) and deploys on GitHub
npm run prod:full # the same, plus a second run that includes the prerender crawl- Every push to
maindeploys. Follow a run withgh run watchor in the repo's Actions tab. - Run workflow in the Actions tab has two switches:
prerender(full build with the crawl) anddeploy(untick to test a build without publishing). - A newer push cancels a run still in progress. If a build fails, the site keeps serving the last good deploy.
Rollback (legacy local deploy): the old gh-pages scripts still exist (npm run deploy, deploy:lite, deploy:fast, deploy:retry). They push dist/client to the gh-pages branch, which only goes live if the Pages source is switched back to "Deploy from a branch: gh-pages" in the repo settings.
Stories are managed via git subtrees. Because subtree remotes are not tracked by git, you must initialize the remote once after cloning:
npm run init-stories: Initialize the stories remote URL (only needed once).npm run pull-stories: Sync stories from the remote repository.npm run push-stories: Push local story changes to the remote repository.
- Contributing: Please read our CONTRIBUTING.md for guidelines on commit messages and content updates.
- Styling: We use Tailwind. Keep it Brutalist yet polished.
- Components: Always use
CustomDropdown,BrutalistDialog, andCustomSliderfor UI consistency. - Icons: We use
@phosphor-icons/react. Always use the ones ending inIcon(e.g.,CpuIcon). - Logic: Use Context for global settings like Visual Effects and Achievements.
If you are modifying or expanding the functionality of Fezcodex, follow these specific architectural patterns:
Commands are used in the Commands Page and the Command Palette. To update them, you must touch three places:
src/data/commands.js: Update the UI data (title, description, icon color) for the/commandspage.src/hooks/useCommandRegistry.js: Implement the actual logic/handler for what the command does.src/hooks/useSearchableData.js: Update thecustomCommandslist so the Command Palette (Ctrl + K) can "find" the command.
The site-wide search (Command Palette and Search bar) is powered by a unified registry:
- Automatic: Blog posts, Projects, and Logs are automatically indexed from their respective
.jsonand.pimlfiles in thepublic/directory. - Manual: Static pages and custom commands must be manually added to the
staticRoutesorcustomCommandslists insrc/hooks/useSearchableData.js.
Every core component should be Theme-Aware:
- Switcher Components: Components like
CommandPalette.jsx,SidePanel.jsx, andGenericModal.jsxact as controllers. They detectfezcodexThemeand render either aBrutalistXorLuxeXvariant. - Universal Styles: Prefer the
variant="brutalist"orvariant="paper"props for shared components likeCustomDropdownto maintain consistency.
- Use
VisualSettingsContext.jsxfor any UI state that needs to survive a page refresh (Invert mode, Theme selection, etc.). - Use
usePersistentStatehook to automatically sync your context variables withlocalStorage.
- Blog posts: write
public/posts/<slug>.txtand add an entry at the top ofpublic/posts/posts.json(slug, title, date, updated, description, tags, category, filename, authors). - Discovery logs: add an
(item)topublic/logs/<type>/<type>.pimland an optional<slug>.txtbeside it. - Every post, log and project needs tags; run
npm run generate-tagsafterwards, thennpm run lint.
- Settings → Pages → Source: GitHub Actions (the workflow is
.github/workflows/deploy.yml). - Custom domain:
fezcode.com, with HTTPS enforced.
Created by Ahmed Samil Bulbul.
