Infinity Notes

Infinity Notes is a small TypeScript monorepo for publishing interconnected markdown notes as a browsable knowledge graph.

It has three runtime parts:

• @infinity-notes/note-processor parses markdown notes, wiki links, backlinks, note previews, concepts, and thread breadcrumbs.
• @infinity-notes/worker serves the note API from Cloudflare Workers and R2.
• @infinity-notes/frontend renders the notes in a Vite React app.

The create-infinity-notes CLI creates a book content directory with metadata, starter notes, and an upload script.

Quickstart

Install dependencies and verify the workspace:

pnpm install
pnpm verify

Build all packages:

pnpm build

Run the test suite:

pnpm test

Create a Book

Run the CLI without installing it:

npx create-infinity-notes my-book

Install it globally if you want a reusable local command:

npm install -g create-infinity-notes
create-infinity-notes my-book

Both entrypoints start the same interactive scaffold. The first positional argument seeds the default book id and the output directory name. The CLI then prompts for:

• book title
• book id
• authors
• description
• R2 key prefix

Example session:

$ npx create-infinity-notes my-book
│
◇  Book title?
│  My Book
◇  Book id?
│  my-book
◇  Authors? (comma-separated)
│  Author One, Author Two
◇  Book description?
│  A networked note set
◇  R2 key prefix?
│  books
│
└  Done! Next steps:

   cd my-book
   edit notes/
   ./upload.sh my-book

It creates a directory like this:

my-book/
  meta.json
  notes/
    Welcome.md
    About.md
    concepts/
      .gitkeep
    threads/
      .gitkeep
  upload.sh
  wrangler.toml
  README.md

After scaffolding:

1. cd my-book
2. Edit the markdown files under notes/
3. Upload the book content with ./upload.sh my-book

The generated README.md inside the book directory repeats the upload basics, and upload.sh uses the scaffolded book id by default. Passing the book id explicitly keeps the command obvious when you are scripting or sharing steps.

To publish the book content to R2 and trigger an index rebuild:

cd my-book
INFINITY_NOTES_BUCKET=your-r2-bucket \
INFINITY_NOTES_R2_PREFIX=books \
INFINITY_NOTES_WORKER_URL=https://your-worker.workers.dev \
./upload.sh my-book

The upload script writes meta.json and every notes/**/*.md file to R2, then calls the worker rebuild endpoint for that book. You can override:

• INFINITY_NOTES_BUCKET for the target R2 bucket name
• INFINITY_NOTES_R2_PREFIX for the root key prefix, such as books or staging/books
• INFINITY_NOTES_WORKER_URL for the deployed worker base URL

Note Format

Notes are markdown files. The filename, relative to notes/, becomes the note path. For example, notes/concepts/Feedback Loop.md becomes concepts/Feedback Loop.

Use front matter for metadata:

---
title: Feedback Loop
snippet: A cycle where outputs influence future inputs.
type: concept
---

# Feedback Loop

A feedback loop connects outputs back into future inputs.

See [[Compounding]] and [[Small Notes Become Systems]].

Supported front matter:

• title: display title; defaults to the note path.
• snippet: short preview text; defaults to the first non-heading lines.
• type: optional concept or thread.
• parent: parent note path or title, used for thread breadcrumbs.
• source_chapter: optional numeric chapter path, such as [1, 2].

Link between notes with double brackets:

This note references [[Feedback Loop]].

The processor resolves links against note paths and titles, builds backlinks, and emits hydrated note JSON for the frontend.

Run Locally

Run the worker API:

pnpm --filter @infinity-notes/worker dev

Run the frontend:

pnpm --filter @infinity-notes/frontend dev

The frontend dev server proxies /api requests to http://localhost:8787. For production builds, set VITE_API_URL if you need to override the default worker API URL:

VITE_API_URL=https://your-worker.workers.dev/api pnpm --filter @infinity-notes/frontend build

Package Overview

packages/
  create-infinity-notes/  CLI for creating book content directories
  note-processor/         Markdown parsing, links, backlinks, previews, indexing
  worker/                 Hono API for Cloudflare Workers and R2
  frontend/               Vite React frontend

Useful package commands:

pnpm --filter create-infinity-notes build
pnpm --filter @infinity-notes/note-processor test
pnpm --filter @infinity-notes/worker build
pnpm --filter @infinity-notes/frontend build

Worker API

The worker exposes:

• GET /api/books
• GET /api/books/:bookId/previews
• GET /api/books/:bookId/concepts
• GET /api/books/:bookId/note/*
• POST /api/books/:bookId/rebuild

Book content is stored under:

<R2_PREFIX>/<bookId>/meta.json
<R2_PREFIX>/<bookId>/notes/**/*.md

Rebuilding a book reads markdown from R2 and writes generated JSON indexes:

<R2_PREFIX>/<bookId>/_previews.json
<R2_PREFIX>/<bookId>/_notes/<notePath>.json
<R2_PREFIX>/_catalog.json

Deployment Basics

Configure the worker R2 binding in packages/worker/wrangler.toml:

[[r2_buckets]]
binding = "NOTES_BUCKET"
bucket_name = "your-r2-bucket"

[vars]
R2_PREFIX = "books"

Deploy the worker with Wrangler:

pnpm --filter @infinity-notes/worker build
cd packages/worker
pnpm exec wrangler deploy

Build the frontend with the deployed worker API URL:

VITE_API_URL=https://your-worker.workers.dev/api pnpm --filter @infinity-notes/frontend build

Deploy packages/frontend/dist with your static hosting provider.

Examples

Only sanitized examples are committed to this repository.

• examples/demo-basic/ contains a small public note graph.
• Private, generated, or book-derived examples are intentionally ignored.

Release Safety

Before publishing packages or pushing a public release, run:

pnpm pack:check
pnpm verify

pnpm pack:check verifies that:

• only public-safe example files are visible to git;
• every publishable package has a files allowlist;
• npm package dry-runs do not include examples, local env files, build caches, Wrangler state, or nested dependencies.

Contributing

Use pnpm for workspace operations. Keep generated content, private examples, local R2 state, and dependency directories out of commits.

For changes that affect package output, run:

pnpm verify