Settings

Site name, content paths and navigation order

Set the site name, content paths and navigation order in for-humanity.config.ts. The file and each item are optional, and omitted items use their defaults.

Create a configuration

Create for-humanity.config.ts in the project root.

import type {SiteConfig} from "for-humanity";

export default {
    title: "Project notes",
    description: "Usage guide and reference documents for the project",
    content: {root: "content", public: "public", private: "private"},
    navigation: ["Start", "Guide", "Updates"],
} satisfies SiteConfig;

With SiteConfig, your editor autocompletes the configuration items and flags incorrect types. Configuration values are validated when you run a command. If you change the configuration during development, restart the server.

If you use JavaScript, export the same object from for-humanity.config.mjs.

// @ts-check
/** @satisfies {import("for-humanity").SiteConfig} */
export default {title: "Project notes"};

Keep only one of .ts and .mjs in a project.

Site

KeyUseDefault
titleSite name in the sidebar and the browser tabfor humanity
descriptionDescription of the home page in search results and link previewsNone
langDocument language tag, for example en, en-USko
localesTranslation languages, see Languages. Supported since 0.22.0None
basePathURL path to deploy under, for example /project/. Supported since 0.17.0/
urlRoot address of the deployed siteNone
imagePath of the link preview image relative to the content rootNone
statusImagePath of the 404 screen image relative to the content root. Supported since 0.20.0Sad expression of the default pixel face
portPort for dev and preview, an integer from 1 to 655354321
hostListening address for dev and preview. Supported since 0.21.0localhost
cursorFacePixel face that follows the mouse on desktopfalse
linkTargetWhere a link in the body opens, new-tab or same-tab. A #hash link to the same page stays in the current tab. Supported since 0.32.0new-tab

Write the title and body of the site home in content/README.md. The description of a document page uses the label of each document. If you set url, crawler files, canonical URLs and link preview tags are generated. Use image together with url and point it to a PNG, JPEG, GIF or WebP file. For the URL format and the output, see Crawling.

Links in the body open in a new tab by default, so the page being read stays where it is. Set linkTarget to same-tab to navigate in the current tab. A #hash link to a heading on the same page always stays in the current tab, and a raw HTML link with its own target keeps it.

Local server

host is supported since 0.21.0.

To allow access from other devices on the same network, configure it as follows.

import type {SiteConfig} from "for-humanity";

export default {
    host: true,
    port: 9999,
} satisfies SiteConfig;
ValueBinding
Omitted or falseListens on localhost only
trueListens on all network interfaces
"0.0.0.0"Listens on all IPv4 interfaces
IP or hostname stringListens on the specified address, for example "192.168.1.144", "::1", "localhost"

Do not add a protocol such as http:// or a port such as :9999 to the address. Set the port separately in port. Restart the server after the change. This setting applies to dev and preview. To change it just once, use the CLI --host, and the CLI option takes precedence over the configuration. For the address to open in the browser and how to share only the public documents, see Commands.

Status screen

The shared 404 screen and statusImage are supported since 0.20.0.

A missing document is shown with a pixel face in the center, the number 404, a message and a link back to the home page. The screen follows the light and dark themes, and you can read it and navigate without JavaScript. build generates the same screen at <content.root>/dist/404.html, and dev and preview return this screen with HTTP 404 for a missing document. The error screen is excluded from the search index. 404.html is a reserved path for the generated error file. You cannot use a document name that produces the same path, such as 404.html.md.

To replace the image, put the file inside the content root, for example content/asset/status.svg, and configure it.

import type {SiteConfig} from "for-humanity";

export default {
    statusImage: "asset/status.svg",
} satisfies SiteConfig;

The path is relative to content.root. SVG, PNG, JPEG, GIF, WebP and AVIF are supported, and you can use it without url. A public build cannot use a file in the private folder or outside the content root. If you changed the file, build again. This setting changes only the picture on the 404 screen and keeps the favicon and the cursor face. If you omit it, the default sad pixel face is used.

Content paths

KeyRelative toDefault
content.rootProject rootcontent
content.publicContent rootpublic
content.privateContent rootprivate

With the defaults, the home page is content/README.md, the public documents are in content/public and the private documents are in content/private. The public folder is required. If you have no private documents, you can omit the private folder.

To use different names, specify them as follows.

import type {SiteConfig} from "for-humanity";

export default {
    content: {root: "knowledge", public: "published", private: "internal"},
} satisfies SiteConfig;

In this case, the home page is knowledge/README.md, the documents are in knowledge/published and knowledge/internal, and the output is in knowledge/dist. The configuration file stays in the project root. The URL of the public document published/guide.md is /guide/. The URL of the private document internal/plan.md is /private/plan/ in dev and in the private site.

Use relative paths within the project. content.root: "." is also possible, but public and private must be different subfolders. The two paths cannot be the same, and neither can be inside the other. A path that contains .., dist, dist-private, .git or node_modules cannot be used. dist-private is reserved since 0.33.0. The public folder and the private folder themselves cannot be symlinks. A symlink also cannot point outside the project or to a reserved folder.

Public and private content

dev shows both kinds of documents. build generates only the home page and the public documents. Check the result with preview. build --private generates a separate site that contains both kinds in dist-private. See Build the private site. The build fails if the home page or a public document references a private document, image, attachment or code snippet.

Keep shared assets in content/asset and private assets in content/private/asset. You can rename asset freely, and you only need to update the links. No separate configuration is required. private is a rule that excludes content from the public site. It does not change the access permissions of files you pushed to a Git repository.

Languages

A site has one default language and any number of translations. The default language uses lang, description, content/README.md and content/public. Each translation lives in a folder named after its language code, with its own README.md home page and a public folder that mirrors the default one.

import type {SiteConfig} from "for-humanity";

export default {
    lang: "en",
    description: "Project notes",
    locales: {
        ko: {description: "프로젝트 안내"},
    },
} satisfies SiteConfig;
KeyUseDefault
localesTranslation languages keyed by language code. Each value can set the description of that language’s home pageNone

The key is a lowercase BCP 47 language tag such as ko or zh-hans. It is the folder name under the content root, the URL prefix and the lang attribute of the translated pages.

content/
├── README.md             # /
├── public/
│   └── guide.md          # /guide/
└── ko/
    ├── README.md         # /ko/
    └── public/
        └── guide.md      # /ko/guide/

A file at the same relative path is the translation of the default document. The sidebar lists only the documents of the current language, and the site name links to the home page of the current language. A page that exists in two or more languages shows a language line above its body that links to each translation. The current language is plain text, and a page without translations shows no line.

Private documents are not translated, and content/asset is shared by every language. A translated document references a shared asset with one more ../, for example ../../asset/screen.png. A plain parent id in a translated document refers to a document of the same language, and a parent in another language is an error. A public document of the default language cannot use a language code as its first path segment.

If you set url, pages that exist in two or more languages get hreflang alternate links in the HTML head and in the sitemap. The default language is also x-default. See Crawling.

In navigation, list the order in which to show the sidebar groups. Each name must match the group in the document frontmatter.

export default {
    navigation: ["Start", "Guide", "Updates"],
};

Groups not in the configuration appear after the specified groups, in name order. A group with no documents is not shown. Specifying the same group twice is an error. Set the order of documents within a group with the order of each document.

Specify the order of nested groups with an array of names.

export default {
    navigation: [
        "Projects",
        ["Projects", "Research"],
        ["Projects", "Decisions"],
        "Guide",
    ],
};

The configuration above shows Research before Decisions inside Projects. Groups with the same name are separate groups if their full paths differ. For how to write group and parent in a document, see Navigation.

Status badges

You can display specific phrases in the body as status badges. The default phrases are 확인됨 and 확인되지 않았다.

export default {
    status: [
        {phrase: "검토 완료", kind: "verified", date: true},
        {phrase: "확인 필요", kind: "unverified"},
    ],
};
KeyUse
phraseNon-empty phrase to find in the body
kindverified: green, unverified: amber, blocked: red, neutral: gray
dateIf true, a YYYY-MM-DD date that follows is also shown

blocked and neutral are supported since 0.24.0.

Writing 검토 완료 2026-10-01 in a document that uses the configuration above displays the phrase and the date as a single badge. A phrase wrapped in parentheses is also recognized. Phrases inside headings, links and code are not converted. Setting status replaces the default list. To turn the badges off, use status: [].

Reference chips

Supported since 0.24.0.

A link whose text is a configured prefix followed by a number, such as [Q3](questions.md#q3), is shown as a small chip instead of an underlined link. Use it for numbered decisions and questions that the body refers to.

export default {
    refs: [
        {prefix: "Q", color: "violet"},
        {prefix: "B", color: "amber"},
        {prefix: "D"},
    ],
};
KeyUse
prefixOne to three uppercase letters. Each prefix once
colorgray (default), blue, violet or amber

Only a link whose whole text is the prefix and digits becomes a chip, so Q3 matches and Q3a or q3 does not. The link address is not changed. Without refs, links are shown as usual. A heading whose whole text is a prefix and a number, such as ### Q3, is shown as the same chip at the heading’s size, so the chip in the body and the anchor it points to look alike. Supported since 0.25.0. The first word of a Details title is shown as a chip when it is a prefix and a number, such as :::details[Q3 Which unit?]. The rest of the title stays as written, and the whole row still opens the Details.

Appearance

The light and dark themes follow the reader’s system setting. Fonts are included in the build output. There is currently no setting to replace the site theme or fonts.