Koji is a self-hostable dead simple personal website for developers. No database, markdown on disk, and a fast, text-first minimalist layout.
Features
- FastAPI — server-rendered HTML, minimal JavaScript
- Markdown + YAML — pages and posts in
content/ - HTMX — live blog search (progressive enhancement)
- SEO — meta tags, Open Graph, JSON-LD, sitemap, robots
- llms.txt — AI-friendly markdown exports (spec)
- Docker — single-container deploy
Quick start
python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --reload
Open http://localhost:8000.
In development, saving files under content/ reloads markdown and site.yaml on the next request — refresh the browser. Set KOJI_ENV=production in production to cache content in memory.
docker compose up --build # or Docker pytest # after pip install -r requirements-dev.txt
Example blog
See Koji in production: muhammadhaseeb.me
Documentation
Full guides for using and extending Koji:
| Guide | Description |
|---|---|
| Documentation index | Start here |
| Getting started | Install, first post, workflow |
| Configuration | Every site.yaml option |
| Content guide | Pages, posts, frontmatter |
| Theming | CSS and templates |
| Deployment | Docker, production, HTTPS |
| SEO | Search and social previews |
| llms.txt | AI assistant exports |
| Extending Koji | Custom routes, templates, forks |
| Architecture | Code structure for developers |
Customize in 60 seconds
Edit content/site.yaml:
title: "Your Name's blog" author: Your Name email: you@example.com url: https://yourdomain.com
Add content by dropping markdown files — no Python or route changes:
- Post →
content/posts/hello.md→/blog/hello - Page →
content/pages/about.md→/about
Example post (content/posts/hello.md):
--- title: Hello slug: hello date: 2026-06-02 description: My first post. --- Hello, world.
License
MIT — see LICENSE.