jdan/notes

notes

Turn a Notion database into a static site. This project powers notes.jordanscales.com.

Usage

This project is designed for trusted content from a private Notion database. Its HTML escaping has not been audited for untrusted input.

1. Create a new Notion integration
2. Create a database and note its ID from the address bar:
   • https://www.notion.so/[username]/[your database ID, copy this!]?v=[ignore this]
   • Add a column called Filename to set each page's output filename. One page must use index.html.
3. Share that database with your new integration
4. Build and serve the site:

git clone https://github.com/jdan/notes.git
cd notes
npm install
NOTION_SECRET=[your token here] NOTION_DATABASE_ID=[your id here] TWITTER_HANDLE=yourHandle npm run build
BUILD=build npm run serve
# http://localhost:3000

The generated HTML and assets are written to build/ by default.

Configuration

Configuration is provided via environment variables, a .env file, or a config file in the .env format. To specify a config file, set the CONFIG=path/to/your/file.env env var. Here's an example:

# recipes.env
TWITTER_HANDLE=jitl
OG_IMAGE=https://jake.tl/images/jake-pleasant.jpg
BASE_URL=/recipes
NOTION_SECRET=secret_XXXXXXX
NOTION_DATABASE_ID=a3aa29a6b2f242d1b4cf86fb578a5eea

Then to use the config, run:

CONFIG=./recipes.env npm run build

Development

npm install
npm run lint
npm run typecheck
npm test

Build with npm run build. For refactors that should not alter generated pages, use npm run build:compare-fresh to compare a fresh build with the current deployment output without modifying build/.

Notes deployment

The notes deployment has two roles:

1. Hetzner runs this app as a Docker container behind the existing kamal-proxy. It receives the protected Notion webhook, runs builds, and keeps a local generated copy in /opt/notes/site.
2. Cloudflare Pages serves the public static site at the edge. After a successful webhook build, the Hetzner container deploys /opt/notes/site to Cloudflare Pages when Cloudflare env vars are configured.

Runtime state on Hetzner:

/opt/notes/.env     # NOTION_* config and WEBHOOK_SECRET
/opt/notes/site     # generated static site
/opt/notes/data     # sqlite cache

The Notion button should request the Hetzner webhook hostname, not the public Cloudflare Pages hostname:

https://<webhook-host>/webhook/notion?secret=<WEBHOOK_SECRET>

The server also accepts the secret in an x-webhook-secret header. Unauthenticated webhook calls return 401.

Recommended hostnames:

notes.jordanscales.com        # public site, points to Cloudflare Pages
hooks.jordanscales.com        # webhook server, points to Hetzner

Architecture overview

flowchart TD
	Notion["Notion Publish button"] -->|"GET /webhook/notion?secret=..."| HooksDNS["hooks.jordanscales.com DNS"]
	HooksDNS --> Hetzner["Hetzner server"]
	Hetzner --> Proxy["kamal-proxy"]
	Proxy --> Container["notes Docker container"]
	Container --> Auth["server.ts validates WEBHOOK_SECRET"]
	Auth --> Build["tsx index.ts builds from Notion"]
	Build --> Cache["SQLite cache /data/db.sqlite3"]
	Build --> Site["generated static site /app/site"]
	Site --> Wrangler["wrangler pages deploy /app/site"]
	Wrangler --> Pages["Cloudflare Pages project: notes"]
	Pages --> Edge["Cloudflare edge"]
	Reader["Reader browser"] -->|"https://notes.jordanscales.com"| NotesDNS["notes.jordanscales.com DNS"]
	NotesDNS --> Edge
	Edge --> Reader

When you click Publish, Notion requests https://hooks.jordanscales.com/webhook/notion?secret=<WEBHOOK_SECRET>. That hostname points to the Hetzner server, where kamal-proxy terminates and routes the request to the notes Docker container.

server.ts authenticates the request using either the secret query parameter or the x-webhook-secret header. Invalid requests return 401; valid requests start a build and immediately return a JSON response indicating that the build has started.

The container runs the normal build entrypoint, tsx index.ts. The build reads Notion using NOTION_SECRET and NOTION_DATABASE_ID, uses the SQLite cache at /data/db.sqlite3, and writes static HTML and assets into /app/site. On the Hetzner host, that directory is backed by /opt/notes/site.

After the build succeeds, server.ts deploys /app/site to Cloudflare Pages with Wrangler when CLOUDFLARE_PAGES_PROJECT_NAME is configured. Wrangler uses the Cloudflare values in /opt/notes/.env, including CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_PAGES_PROJECT_NAME, and CLOUDFLARE_PAGES_BRANCH.

Cloudflare creates a new Pages deployment for the notes project. Since deployments use branch main, Cloudflare treats the deployment as production and serves it through the custom domain notes.jordanscales.com.

Readers visiting https://notes.jordanscales.com/ hit Cloudflare Pages, not Hetzner. The Hetzner container still keeps and can serve a local generated copy as a fallback, but the intended public browsing path is Cloudflare edge.

Cloudflare Pages setup

Install dependencies locally if needed:

npm install

Log in with Wrangler and create the Pages project once:

npx wrangler login
npx wrangler pages project create notes --production-branch main

If the project already exists, skip the create command. The project name can be anything, but it must match CLOUDFLARE_PAGES_PROJECT_NAME below.

Create a Cloudflare API token for Hetzner. It needs permission to deploy Pages for the account. Use the narrowest token Cloudflare allows for Pages deployments; if account selection is ambiguous, also set CLOUDFLARE_ACCOUNT_ID.

Add these values to /opt/notes/.env on Hetzner:

CLOUDFLARE_API_TOKEN=<cloudflare-api-token>
CLOUDFLARE_ACCOUNT_ID=<cloudflare-account-id> # optional unless Wrangler needs it
CLOUDFLARE_PAGES_PROJECT_NAME=notes
CLOUDFLARE_PAGES_BRANCH=main

Manual deploy from an already-built local build/ directory:

CLOUDFLARE_PAGES_PROJECT_NAME=notes npm run deploy:cloudflare

Manual deploy from Hetzner's generated site directory:

ssh hetzner 'docker exec notes npx wrangler pages deploy /app/site --project-name notes --branch main'

DNS cutover

1. Add notes.jordanscales.com as a custom domain on the Cloudflare Pages project.
2. Point notes.jordanscales.com DNS to Cloudflare Pages using Cloudflare's generated target.
3. Point a separate hostname, for example hooks.jordanscales.com, to the Hetzner server.
4. Deploy the Hetzner service with NOTES_WEBHOOK_HOST=hooks.jordanscales.com npm run deploy:notes.
5. Update the Notion webhook/button URL to https://hooks.jordanscales.com/webhook/notion?secret=<WEBHOOK_SECRET>.

The Hetzner container still serves static files as a fallback, but readers should hit Cloudflare Pages after DNS cutover.

Useful checks:

curl -I https://notes.jordanscales.com/
curl https://hooks.jordanscales.com/healthz
ssh hetzner 'docker logs --tail 100 notes'
ssh hetzner 'docker exec kamal-proxy kamal-proxy list'

To deploy source changes to the running notes service:

npm run deploy:notes

The deploy script syncs source to /opt/notes, preserves remote .env, rebuilds the Docker image, restarts the notes container, and re-registers the route with kamal-proxy. It excludes the local, gitignored build/ directory. Set NOTES_WEBHOOK_HOST when deploying if the Hetzner route should use a hostname other than notes.jordanscales.com.