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 incontent/
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 --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
See Koji in production: muhammadhaseeb.me
Full guides for using and extending Koji:
| Guide | Description |
|---|---|
| Documentation index |
Getting startedConfigurationsite.yaml
optionContent guideThemingDeploymentSEOllms.txtExtending KojiArchitectureEdit content/site.yaml
:
title: "Your Name's blog"
author: Your Name
email: you@example.com
url: https://yourdomain.com
Add a post at content/posts/hello.md
:
---
title: Hello
slug: hello
date: 2026-06-02
description: My first post.
---
Hello, world.
MIT — see LICENSE.