Installation

Install the package

package.json이 있는 프로젝트에서 설치합니다.

pnpm add -D --save-exact for-humanity@0.19.0

0.13.1 이하에서 업데이트한다면 먼저 Migration을 따라 문서와 설정 위치를 변경합니다.

Initialize a site

프로젝트 루트에서 초기화 명령을 실행합니다. 직접 파일을 만들려면 아래 Your first site를 따릅니다.

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

사이트 이름, 문서 폴더, 언어와 배포 방식을 선택합니다. 추천값을 고르거나 같은 질문에서 바로 타이핑합니다. Custom 행으로 이동한 뒤 입력해도 됩니다. 기본 문서 폴더는 content, 언어는 ko, 배포는 나중에 설정입니다. GitHub Pages를 선택하면 저장소와 배포 브랜치를 확인합니다. Cloudflare에서는 Workers를 권장합니다. Workers 초기화는 0.19.0부터 지원하며 Worker 이름, Wrangler 설정과 빌드와 배포 명령을 준비합니다. 기존 Cloudflare Pages 선택도 지원합니다.

생성할 파일을 확인하면 설정, 첫 문서와 docs:* 스크립트를 만듭니다. 초기화 후 pnpm docs:dev 또는 npm run docs:dev를 실행합니다. 필요한 의존성이 없으면 설치 명령부터 안내합니다. init은 패키지를 자동 설치하거나 호스팅 계정을 연결하지 않습니다.

새 폴더는 for-humanity init my-docs로 지정합니다. 기존 문서나 설정, 다른 내용의 docs:* 스크립트와 충돌하면 파일 생성 전에 중단합니다. 자세한 옵션은 Commands, 배포 단계는 Deployment를 참고합니다.

Your first site

content/public 폴더를 만들고 홈에 표시할 내용을 content/README.md에 작성합니다. 기본 파일을 복사해서 시작하려면 아래 Content layout을 참고합니다.

# Project notes

프로젝트 소개와 사용 안내입니다.

[시작하기](public/guide.md)

content/public/guide.md에는 문서 정보와 본문을 작성합니다.

---
name: Guide
label: 처음 사용하는 사람을 위한 안내
group: Guide
order: 10
---

## Overview

첫 번째 문서입니다.

프로젝트 루트에서 실행합니다.

pnpm exec for-humanity dev

http://localhost:4321/에서 홈과 Guide 문서를 확인합니다. Markdown을 저장하면 열린 페이지가 새로고침됩니다. 설정 없이도 기본 경로로 실행할 수 있습니다. 설정을 추가할 때는 프로젝트 루트에 for-humanity.config.ts를 둡니다.

배포할 결과를 만들고 확인합니다.

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

출력은 content/dist입니다. 홈과 content/public의 문서만 배포 결과에 포함합니다.

Content layout

설정은 프로젝트 루트에 두고 문서는 공개 폴더와 내부 폴더로 구분합니다.

설치된 node_modules/for-humanity/template에서 설정 파일과 content 폴더를 자신의 프로젝트로 복사합니다. 기존 파일이 있다면 필요한 항목만 병합합니다.

project/
├── for-humanity.config.ts
└── content/
    ├── README.md
    ├── public/
    │   └── getting-started.md
    ├── private/
    └── asset/

• README.md: 사이트 홈에 표시할 소개
• public: 배포할 문서
• private: 로컬에서만 읽을 문서
• asset: 공개 문서에서 사용할 이미지와 첨부

dist는 빌드할 때 생성되므로 .gitignore에 content/dist/를 추가합니다. 폴더 이름을 바꾸는 설정은 Settings를 참고합니다.

문서 작성은 Writing, 명령의 자세한 동작은 Commands, 결과 공개는 Deployment로 이어집니다.