self-hosted-knowledge-base

A complete toolkit to publish a beautiful, zero-cost, self-hosted personal knowledge base using only free infrastructure.

• Free subdomain via DigitalPlat
• Hosting + custom domain via Cloudflare Workers
• One Python script that converts a folder of Markdown notes (with frontmatter, math, images, tables) into self-contained HTML pages + the Worker that serves them

Live example: yren.dpdns.org

Why This Exists

Most note-taking apps lock your thinking inside proprietary databases and subscription funnels. This system gives you:

Why This Exists

Most note-taking apps lock your thinking inside proprietary databases and subscription funnels. This system gives you:

• True ownership: Plain .html files + one index.js. No vendor can take them away.
• Universal access: Open any note in any browser, today or in 15 years. No logins, no apps, no "export".
• Zero cost: Free domain + Cloudflare's generous free tier (effectively unlimited for personal use: 20k files, 25MB each in the Worker model).
• LLM-powered craft: You think and write in Markdown (or let Claude turn transcripts/raw notes into Markdown). The script + LLMs handle the beautiful, self-contained presentation.
• Simple maintenance: Run one script to regenerate. One command to deploy. Git-track everything.

The files are the website. The HTML pages are completely self-contained (Tailwind CDN + KaTeX for math + one Google font). They look great on mobile and desktop.

How It Works (High Level)

Your Markdown notes/          generate_site.py
     (with **Category:**        -------------->   site/*.html   +  index.js (Worker routes)
      **Date:**, images,          (parses MD,     (all assets bundled as
      tables, math, lists)         copies images)   ES modules for Wrangler)

                                               ./deploy  -->  wrangler deploy
                                                                    |
                                                                    v
                                                          Cloudflare edge
                                                                    |
                                                                    v
                                                          https://yourname.dpdns.org

See the flowchart at flowchart.jpg for a visual.

What's in This Kit

• generate_site.py — the core converter + homepage generator + Worker code emitter
• deploy.sh — one-command deploy to Cloudflare
• generate.sh — convenience wrapper for the Python script
• preview.sh — local HTTP server for the generated site/
• wrangler.toml.example — configuration template for the Worker
• notes/ — put your .md files here (or point the script elsewhere)
• SETUP.md — first-time registration + Cloudflare + Wrangler instructions
• WORKFLOW.md — daily use: writing notes, adding images, categories, deploying
• PRIVACY.md — how to add a password-protected /private section with Cloudflare Access (still free)
• example-note.md (in notes/) — a minimal sample you can duplicate

Quick Start (After Initial Setup)

# 1. Drop some Markdown files into ./notes/ (or your own folder)
# 2. Regenerate the site
./generate.sh

# 3. Preview locally
./preview.sh
# open http://localhost:8080

# 4. Deploy
./deploy.sh

See SETUP.md for the one-time domain + Cloudflare + wrangler work.

See WORKFLOW.md for how to write notes that look great.

Requirements

• Python 3 (standard library only — no extra packages)
• Node.js + npm (for Wrangler)
• A Cloudflare account (free)
• A free subdomain from DigitalPlat

Philosophy (from the live example)

You can now turn a completely free subdomain into a personal knowledge base that costs nothing to run and will outlive any note-taking application.

Your notes are not rows in a proprietary database. They are ordinary files in the most universally readable document format ever created.

Zero ongoing cost. Zero migration risk.

Full writeup: the article "Documenting LLM notes with HTML on a FREE personal knowledge website" is itself published on the example site.

Limitations & Trade-offs

• All notes are public by default (add Cloudflare Access for private parts — see PRIVACY.md).
• The Worker bundles everything at deploy time. A few hundred notes is fine; thousands may require splitting or moving images to R2.
• You edit Markdown (or have an LLM do it). There is no WYSIWYG web editor.
• Images are inlined into the Worker bundle (good for small diagrams; large photos are better served differently).

Next Steps

1. Read SETUP.md and get your domain live.
2. Copy notes/example-note.md and start writing.
3. Run ./generate.sh && ./deploy.sh.
4. (Optional) Put the whole folder under git and commit the generated site/ + index.js so you have history of what was published.

This kit was extracted from a working personal site (yren.dpdns.org) and generalized so anyone can run the same pattern with their own notes and domain.

Credits & Provenance

• Pattern originally built and battle-tested at yren.dpdns.org
• Core ideas documented in the essay "Documenting LLM notes with HTML on a FREE personal knowledge website" (itself published using this system)
• Made available as a standalone, documented kit for others to repeat

---

Status: Ready to fork and adapt. Everything here is designed to be copy-pasted into your own folder structure and run with minimal changes.