more (#13)

a10y · web-flow · commit b92b18a81343 · 2026-02-23T15:06:06.000-05:00
- trim CLAUDE.md
- Add some more text to README
- Add github repo link in header

Signed-off-by: Andrew Duffy &lt;andrew@a10y.dev&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,12 +1,12 @@
 # Vortex RFC Site
 
-Static site generator for Vortex RFC proposals.
+Static site generator for Vortex RFC proposals built with Bun.
 
 ## Project Structure
 
 ```
 index.ts      - Main build script and dev server
-styles.css    - Site styling (light/dark themes, monospace aesthetic)
+styles.css    - Site styling (light/dark themes)
 proposals/    - RFC markdown files (format: NNNN-slug.md)
 dist/         - Build output (gitignored)
 ```
@@ -33,125 +33,15 @@ bun run clean    # Remove dist/
 - Uses `Bun.serve()` to serve static files from `dist/`
 - Watches `proposals/` and `styles.css` for changes
 - SSE endpoint at `/__reload` for live reload
-- Live reload script only injected in dev mode
 
 ## Styling
 
 - CSS custom properties for theming (`--bg`, `--fg`, `--link`, etc.)
 - System preference detection via `prefers-color-scheme`
-- Three-state toggle: auto → dark → light → auto
+- Two-state toggle: dark ↔ light
 - Theme persisted to localStorage
 
 ## Adding Features
 
 - Keep dependencies minimal (only `@types/bun` currently)
 - Use Bun built-ins: `Bun.file`, `Bun.Glob`, `Bun.markdown`, `Bun.serve`
-- Maintain the retro monospace aesthetic
-
----
-
-Default to using Bun instead of Node.js.
-
-- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
-- Use `bun test` instead of `jest` or `vitest`
-- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
-- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
-- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
-- Use `bunx <package> <command>` instead of `npx <package> <command>`
-- Bun automatically loads .env, so don't use dotenv.
-
-## APIs
-
-- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
-- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
-- `Bun.redis` for Redis. Don't use `ioredis`.
-- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
-- `WebSocket` is built-in. Don't use `ws`.
-- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
-- Bun.$`ls` instead of execa.
-
-## Testing
-
-Use `bun test` to run tests.
-
-```ts#index.test.ts
-import { test, expect } from "bun:test";
-
-test("hello world", () => {
-  expect(1).toBe(1);
-});
-```
-
-## Frontend
-
-Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
-
-Server:
-
-```ts#index.ts
-import index from "./index.html"
-
-Bun.serve({
-  routes: {
-    "/": index,
-    "/api/users/:id": {
-      GET: (req) => {
-        return new Response(JSON.stringify({ id: req.params.id }));
-      },
-    },
-  },
-  // optional websocket support
-  websocket: {
-    open: (ws) => {
-      ws.send("Hello, world!");
-    },
-    message: (ws, message) => {
-      ws.send(message);
-    },
-    close: (ws) => {
-      // handle close
-    }
-  },
-  development: {
-    hmr: true,
-    console: true,
-  }
-})
-```
-
-HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
-
-```html#index.html
-<html>
-  <body>
-    <h1>Hello, world!</h1>
-    <script type="module" src="./frontend.tsx"></script>
-  </body>
-</html>
-```
-
-With the following `frontend.tsx`:
-
-```tsx#frontend.tsx
-import React from "react";
-import { createRoot } from "react-dom/client";
-
-// import .css files directly and it works
-import './index.css';
-
-const root = createRoot(document.body);
-
-export default function Frontend() {
-  return <h1>Hello, world!</h1>;
-}
-
-root.render(<Frontend />);
-```
-
-Then, run index.ts
-
-```sh
-bun --hot ./index.ts
-```
-
-For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
diff --git a/README.md b/README.md
@@ -2,6 +2,21 @@
 
 This repo is used to store and discuss design decisions, features and significant changes in Vortex, either in specific APIs, 3rd-party integrations or the conceptual model.
 
+## What needs an RFC?
+
+Vortex is a rapidly changing open source project that provides a file format, a compute toolkit, and a set of Rust libraries implementing a range of state-of-the-art compression codecs.
+
+Most development decisions in Vortex happen through the Discussions functionality. Simply open a new discussion describing the kind of change you'd like to make to the project, and if the maintainers like it, open a PR.
+
+This is a great process for bug fixes, simple features and purely additive changes.
+
+However, if you are making a significant change to the way Vortex functions, you may need to write an RFC first. Some example changes that would require an RFC:
+
+* Making a risky change to the format, such as adding new required fields to file metadata
+* Rearchitecting core components of Vortex, or wide-ranging refactors that might break language bindings
+* Creating new libraries or SDKs that we expect others to adopt
+* Making changes to subsystems that are likely to affect performance if not done thoughfully, such as the core IO traits
+
 ## Process
 
 The general process is that changes should be opened as PRs, with the discussion happening in comments on top of it.
diff --git a/index.ts b/index.ts
@@ -42,6 +42,8 @@ const ICON_MOON = `<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18
 
 const ICON_EXTERNAL = `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M7 7h10v10"/><path d="M7 17 17 7"/></svg>`;
 
+const ICON_GITHUB = `<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg>`;
+
 const TOGGLE_SCRIPT = `
 function toggleTheme() {
   const root = document.documentElement;
@@ -72,8 +74,9 @@ const LIVE_RELOAD_SCRIPT = `
 })();
 `;
 
-function baseHTML(title: string, content: string, cssPath: string = "styles.css", liveReload: boolean = false): string {
+function baseHTML(title: string, content: string, cssPath: string = "styles.css", liveReload: boolean = false, repoUrl: string | null = null): string {
   const basePath = cssPath === "styles.css" ? "./" : "../";
+  const githubLink = repoUrl ? `<a href="${repoUrl}" class="github-link" aria-label="View on GitHub" target="_blank" rel="noopener">${ICON_GITHUB}</a>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -91,7 +94,10 @@ function baseHTML(title: string, content: string, cssPath: string = "styles.css"
         <img src="${basePath}vortex_logo.svg" alt="Vortex" class="header-logo">
         <h1>Vortex RFCs</h1>
       </a>
-      <button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme"></button>
+      <div class="header-actions">
+        ${githubLink}
+        <button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme"></button>
+      </div>
     </header>
     <main>
 ${content}
@@ -147,7 +153,7 @@ function indexPage(rfcs: RFC[], repoUrl: string | null, liveReload: boolean = fa
 ${list}
       </ul>`;
 
-  return baseHTML("Vortex RFCs", content, "styles.css", liveReload);
+  return baseHTML("Vortex RFCs", content, "styles.css", liveReload, repoUrl);
 }
 
 function formatDate(date: Date): string {
@@ -212,7 +218,7 @@ function rfcPage(rfc: RFC, repoUrl: string | null, liveReload: boolean = false):
         ${rfc.html}
       </article>`;
 
-  return baseHTML(`RFC ${rfc.number} - ${rfc.title}`, content, "../styles.css", liveReload);
+  return baseHTML(`RFC ${rfc.number} - ${rfc.title}`, content, "../styles.css", liveReload, repoUrl);
 }
 
 function parseRFCNumber(filename: string): string {
diff --git a/styles.css b/styles.css
@@ -116,6 +116,37 @@ header h1 a:hover {
   color: var(--link);
 }
 
+.header-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.github-link {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border-radius: 50%;
+  color: var(--fg-muted);
+  transition: color 0.15s ease, box-shadow 0.15s ease;
+}
+
+.github-link:hover {
+  color: var(--fg);
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.15);
+  text-decoration: none;
+}
+
+:root[data-theme="dark"] .github-link:hover {
+  box-shadow: 0 2px 12px rgba(255, 255, 255, 0.1);
+}
+
+.github-link svg {
+  display: block;
+}
+
 .theme-toggle {
   display: flex;
   align-items: center;
