for humanity
Documents, for humans.
Write Markdown. Keep the context. Share a static site.
Documentation | npm | Releases
Quick start | Guide | Commands | Deployment | Korean
Write, organize, publish
Write Markdown with code examples, tables and Mermaid diagrams, and add images, video and audio. Organize pages into groups and nested navigation. Use notes for context and collapsible details for longer explanations. Add translations as a folder per language.
The result is a static site with bundled fonts, light and dark themes, keyboard navigation and a layout that adapts to narrow screens.
Quick start
You need Node.js 22.12.0 or later and pnpm. In a project with a package.json, install the package:
pnpm add -D --save-exact [email protected]
Copy for-humanity.config.ts and the content folder from node_modules/for-humanity/template into your project. If you already have documentation, follow Migration before moving files.
Edit content/README.md for your home page:
# Project notes
Welcome to the project documentation.
Start the local server:
pnpm exec for-humanity dev
Open localhost:4321. Edit the Markdown file and save to update the page. Follow Installation to add your first document.
Build and inspect the site before deployment:
pnpm exec for-humanity build
pnpm exec for-humanity preview
Deploy the generated content/dist directory and add it to .gitignore. See Deployment for hosting settings.
Keep published documents in content/public and local notes in content/private. The local server shows both; builds include only public documents and the home page. Folder names are configurable.
Interactive setup
Instead of copying the template, run pnpm exec for-humanity init (npx for-humanity init with npm).
The setup asks for a site title, documentation folder, language and hosting target: GitHub Pages, Cloudflare Workers, Cloudflare Pages or later. It prepares the configuration, first document and docs:dev, docs:build and docs:preview scripts. Hosting setup creates deployment files and shows the remaining service settings. Workers setup also prepares Wrangler and a docs:deploy script.
Existing application scripts and dependencies are kept. Review the file list before creation. See Commands for options and automation.
Make it yours
Set the site name, page language and the order of navigation groups:
import type {SiteConfig} from "for-humanity";
export default {
title: "Project notes",
description: "A guide to using the project.",
lang: "en",
navigation: ["Start", "Guide", "Updates"],
} satisfies SiteConfig;
Save this as for-humanity.config.ts in the project root, alongside package.json. Existing .mjs configuration is also supported; keep only one configuration file.
Each document declares a title, description and navigation group in frontmatter. See Writing for a complete example and Settings for available options.
Keep useful detail
:::note[Before you start]
Check the requirements before following the steps.
:::
:::details[More information]
Add examples or explanations readers can open when needed.
:::
Parts shows the syntax alongside its rendered output.
Documentation
License
MIT © 2026 nomeehej
