Personal Wiki as a Static Site Learning Project. A Build Next Stack field guide for learners shipping small projects.
Why static beats dynamic for your first wiki
A personal wiki is where you store definitions, setup notes, and half-finished ideas—not content for strangers. Building it as a static site means every page is a file in Git, preview is opening HTML or running a tiny build, and hosting is any object storage or free static host. You skip login flows, session cookies, and database backups until you actually need collaboration.
The stack lesson: folder structure as navigation, markdown as source of truth, and a build step you understand line by line. Pick Eleventy, Hugo, or a twenty-line Python markdown script—tool matters less than owning the pipeline. Success looks like thirty notes you actually search by filename because the index page lists them honestly.
Write a one-paragraph CONTRIBUTING.md for future you: how to add a note, how to rebuild, how to fix broken links. Wikis die when the build steps live only in memory. Paper docs beat clever automation you forget.
Milestone one: folder structure and one index page
Organize with top-level buckets that match how you think, not how apps label tabs:
- notes/ — evergreen reference (API keys rotation steps, printer IP).
- projects/ — one file per active side project with status header.
- journal/ — dated entries, optional, if you mix daily logs with wiki.
Generate an index page that lists every markdown file with title (first H1) and last modified date from Git or filesystem. No JavaScript search yet—an honest list beats a broken fuzzy finder. Acceptance: add a new note, rebuild, index shows it without hand-editing HTML.
Slug rule: lowercase hyphenated filenames match URL paths. notes/docker-reset.md becomes /notes/docker-reset.html. Predictable URLs are the wiki’s API.
Add a README at repo root explaining the three folders in two sentences each. New contributors—usually you in six months—should know where to file a note without reading the generator docs.
Milestone two: markdown to HTML without mystery plugins
Configure one markdown renderer and stop. Support headings, lists, links, code fences, and blockquotes—that covers ninety percent of personal notes. Enable syntax highlighting only if your build tool makes it one line; do not compile custom highlighters on day two.
Wrap each page in a shared layout: site title, breadcrumb back to index, footer with build timestamp. The layout file is the right place for a single CSS file under five kilobytes—readable font, max-width, monospace code blocks. Dark mode is optional v2; readable contrast is mandatory v1.
Internal links use relative paths between generated HTML files. Write one note linking to another; click works on file:// preview and on the deployed host. Broken relative links are the primary failure mode; add a script that greps for .md links and warns before deploy.
Front matter optional: if your generator supports YAML headers, store title and updated there instead of scraping H1. Consistency beats auto-magic that breaks when you forget the hash line.
Acceptance checks for navigation and search
Before calling v1 done:
- Twenty real notes imported—not lorem ipsum placeholders.
- Index fits on one scroll on laptop; entries sorted by folder then title.
- Mobile width readable without horizontal scroll on a phone browser.
- Build command documented; runs in under ten seconds on your machine.
- Deploy produces HTTPS URL you can open from phone.
“Search” for v1 is browser Find on the index page plus consistent naming. If you add client-side search later, index note titles only— not full body text—to keep payload small.
Local preview habits that catch broken links early
Run preview on a fixed port and leave it open while editing. Each save triggers rebuild if your tool supports watch mode; otherwise rerun build manually until muscle memory forms. Click every new internal link once—keyboard navigation skips the failure mode where markdown looks fine but href paths are wrong.
Print build duration in the terminal. Static wikis should rebuild in seconds; if yours takes a minute, investigate plugin bloat before adding more features. Slow feedback loops cause you to preview less, which causes more broken deploys.
Keep a TODO.md in the repo listing orphan notes (not linked from index) and fix one per week. Orphans are fine for drafts; orphans you forgot about become stale facts you trust incorrectly.
Traps when copying blog templates
Trap: theme shopping for a week. Blog themes assume posts, tags, RSS, comments. You need pages and an index. Start from the generator’s barebones starter, not a magazine layout.
Trap: wikilinks before basic links work. [[Note title]] syntax requires a resolver and orphan detection. Use standard markdown links until you have fifty notes.
Trap: publishing pipeline you cannot run offline. If deploy requires three proprietary CLI logins, simplify. Git push to static host or rsync to a folder you control.
Trap: mixing public and private in one repo. Secrets belong in a private vault, not a “private” page that accidentally deploys. Keep the wiki public-safe; link out to password manager entries instead.
Publishing without a build chain you cannot debug
Document the pipeline as three named steps: build, preview, deploy. Preview serves locally on a fixed port; deploy uploads the _site or public output only—never source markdown mixed with HTML on the server.
Add a .nojekyll or equivalent if your host ignores underscored folders. Set cache headers or hashed asset names only if you have CSS/JS beyond one file; for text-heavy wikis, simple is fine.
When build breaks, error message should name the offending markdown file and line. If the tool dumps a stack trace, wrap it in a script that prints FAILED: notes/example.md and exit 1. You will break builds often; fast diagnosis keeps the wiki alive.
Migrate ten notes you already have scattered
Move ten real notes from Apple Notes, Notion, or desktop txt files into the repo this week. If migration hurts, adjust folder names—not the build tool. A wiki nobody writes in is static hosting practice, not a knowledge base.
Deploy once to a URL you will bookmark. Send yourself one linked page on your phone. That friction test reveals broken navigation faster than localhost ever will.
Keep the build script under fifty lines if you rolled your own. The goal is transparency: when something breaks, you read code instead of Discord threads.