Koji is a self-hostable dead simple personal website for developers. No database, markdown on disk, and a fast, text-first minimalist layout.
- 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
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reloadOpen 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.txtSee Koji in production: muhammadhaseeb.me
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 | New pages, routes, forks |
| Architecture | Code structure for developers |
Edit content/site.yaml:
title: "Your Name's blog"
author: Your Name
email: you@example.com
url: https://yourdomain.comAdd a post at content/posts/hello.md:
---
title: Hello
slug: hello
date: 2026-06-02
description: My first post.
---
Hello, world.MIT — see LICENSE.