Commands

init, dev, build and preview commands and troubleshooting

Run the commands from the project root with pnpm exec for-humanity. For installation, see Installation.

for-humanity <init|dev|build|preview> [project-dir]
CommandResult
initChoose the site information and deployment method, then create the first document and the run scripts
devView public and private documents together, reload on change, runs when the command is omitted
buildGenerate the home page and public documents in content/dist
build --privateGenerate a separate site that also contains the private documents in content/dist-private
previewView the last build output
preview --privateView the last output of build --private
--help or -hCommand help
--version or -vInstalled version

project-dir is the project root that contains the configuration file, and it defaults to the current folder when omitted. To run from another folder, specify the project path, as in for-humanity dev ../my-project. If you changed content.root, the output is dist under that folder. init is supported since 0.18.0.

Initialize a project

cloudflare-workers and --worker-name are supported since 0.19.0. For the deployment steps and the manual setup, see Cloudflare Workers.

pnpm exec for-humanity init
pnpm exec for-humanity init my-docs
# npm
npx for-humanity init

Prompts appear only for values you did not specify. The suggested values are the project name for the site name, content and docs for the folder, and Korean and English for the language. You can type directly at a suggested value or move to the Custom row to enter your own. A single Enter confirms an answer. You also confirm the detected GitHub repository and branch by accepting the suggestion or typing your own. Before creating files, it shows the selected settings and the file list. If you cancel with Ctrl+C or with No at the final confirmation, it exits with code 130 without creating any files.

OptionValue
--titleSite name, defaults to the name in the existing package.json or Project notes
--contentContent folder inside the project, defaults to content
--langDocument language tag, defaults to ko
--deploynone, github-pages, cloudflare-workers, cloudflare-pages
--worker-nameA name unique within the Workers account. Suggests an available project name or for-humanity-docs
--repositoryGitHub repository owner/name, suggested when a single one is identified from local Git
--branchGitHub deployment branch, local main/master or main
--urlPublic HTTP(S) domain, a GitHub site with a separate domain is created with a root path
--managernpm or pnpm, detected from the declaration, lockfile, and runtime environment
--yesSkip prompts and confirmation, an unspecified deployment method is none

Non-interactive examples:

pnpm exec for-humanity init --yes --deploy none
pnpm exec for-humanity init --yes --deploy github-pages --repository username/project --branch main
npx for-humanity init --yes --deploy cloudflare-workers --worker-name team-docs --manager npm

In non-interactive environments, specify --yes or --deploy. GitHub Pages requires repository information. Options you provide are validated even with --yes. The package manager is chosen in this order: explicit option, packageManager, lockfile, runtime environment. If the declaration and the option conflict, or it cannot choose between two lockfiles, it explains how to fix the problem.

It keeps your existing dev and build scripts and the for-humanity dependency version, and adds only docs:*. It does not overwrite existing configuration, documents, or hosting files. For a project that is already initialized, edit the configuration directly. To move existing documents, follow Migration.

While editing

dev reflects changes to Markdown, the home page, images, and snippets. If you save an invalid document, it shows the error in the terminal and keeps the last valid document. Fix the error and save again, and the document is reflected again. If you change the configuration file, stop the server and run it again.

preview shows the last build output. If you edited documents, run build again. Both servers use localhost and port 4321 by default. If the port is in use, stop the existing server or set a different port with port in the configuration.

Connect over a local network

--host and host in the configuration are supported since 0.21.0.

To connect from another device on the same network, add --host. If you omit the value, the server accepts connections on all IPv4 interfaces.

pnpm exec for-humanity dev --host
# dev runs even when the command is omitted
pnpm exec for-humanity --host
# Use only a specific interface
pnpm exec for-humanity dev --host 192.168.1.144

If port in the configuration is 9999, connect from another device at http://192.168.1.144:9999. Replace the example IP with the real IP of the computer running the server. 0.0.0.0 is a listening address setting, not an address to type into a browser. You can use the Network address shown in the terminal. If the connection fails, check that both devices are on the same network and that the firewall allows the port.

To apply it every time, set host in Settings. The CLI --host takes precedence over the configuration file and does not apply to build. Do not include a protocol or a port in the address. Specify the port with port in the configuration.

dev also shows private documents. To share only the public documents, build and then run preview.

pnpm exec for-humanity build
pnpm exec for-humanity preview --host

Build the private site

--private is supported since 0.33.0.

build --private generates a site that contains the public documents and the private documents together. It is the same site that dev shows. The output goes to content/dist-private, and content/dist stays as it is.

pnpm exec for-humanity build --private
pnpm exec for-humanity preview --private

preview --private serves dist-private on your computer so that you can check the result. It has no access control, so use it only locally. Use the private site to share private documents with the people you allow. Deploy dist-private only to hosting that puts the whole site behind access control. See Private site.

Help and troubleshooting

pnpm exec for-humanity --help
pnpm exec for-humanity build --help
pnpm exec for-humanity --version
SituationWhat to check
Content folder not foundThe installed version, the positional argument of the command, and the content.root setting
frontmatter errorThe YAML syntax of the document named in the error, and whether name, label, and group exist
Duplicate configuration fileWhether both .ts and .mjs exist in the same location
private reference errorWhether the home page or a public document links to private material
preview shows no changesWhether you rebuilt after editing