이 문서 만들기와 고치기
이 사이트는 Markdown을 빌드한 정적 HTML이에요. 쓰고, 빌드하고, 스크린샷을 다시 찍고, 코드가 바뀐 곳을 찾고, 버전을 나누는 법이에요.
이 사이트는 워크스페이스의 docs/ 폴더에 있어요. Markdown 원본을 npm run build로 정적 HTML(dist/)로 만들고, 그 폴더를 어느 정적 호스팅에 올려도 돼요. 글꼴과 검색 색인까지 함께 나가서 폐쇄망에서도 돌아요.
폴더
| 경로 | 무엇 |
|---|---|
content/<언어>/<제품>/<페이지>.md |
원본. 언어는 ko, en. 제품은 home(이 제품군 페이지들), galpi, mothership, naru, golden-image |
nav.yaml |
제품(왼쪽 위 전환 메뉴)과 페이지 순서 |
sources.yaml |
저장소마다 이 문서를 확인한 커밋 |
versions.yaml |
문서 버전 목록 |
shots/<언어>/<제품>/<이름>-<light|dark>.webp |
스크린샷 |
theme/ |
페이지 틀(layout.mjs), 스타일, 스크립트. 갈피의 디자인 값을 그대로 써요 |
scripts/ |
빌드, 미리보기 서버, 스크린샷, 변경 추적, 버전 나누기 |
쓰기
---
title: 페이지 제목
nav_title: 목록에 보일 짧은 이름 (선택)
description: 제목 아래 한두 문장
sources: # 이 페이지가 기대는 소스 (변경 추적에 써요)
- galpi:docs/설치와-설정.md
- galpi:apps/server/src/config.ts
keywords: [설치 방법, 배포] # 본문에 없지만 사람들이 찾을 말 (검색에만 쓰고 보이지 않아요)
---
본문은 Markdown이에요. 다른 페이지는 언어 없이 /galpi/install/ 처럼 적어요.

::: tip 제목(선택)
note, tip, warning, danger 상자
:::
::: steps
1. 번호가 붙은 단계
:::
- 사이트 안 링크는 언어와 버전이 저절로 붙고, 빌드가 없는 페이지를 가리키는 링크를 찾아 실패시켜요.
shot:이미지는 그 언어의 스크린샷을 쓰고, 없으면 다른 언어의 것을, 그것도 없으면 자리 표시를 보여 줘요. 밝게·어둡게가 둘 다 있으면 테마에 맞춰 바뀌어요.- 두 언어의 같은 경로 파일이 서로의 번역이에요. 한쪽만 고치지 않아요.
- 검색(Pagefind)은 쓴 그대로 못 찾으면 갈피의 채팅 검색과 같은 규칙으로 다시 찾아요. 한국어 조사·어미를 떼고, "어떻게" 같은 물음의 말을 빼고, 그래도 없으면 오른쪽 단어부터 하나씩 빼요(
theme/assets/site.js). 본문에 없는 말로 자주 찾는 페이지에는keywords:를 적어요.
빌드와 미리보기
cd docs
npm install
npm run build # dist/ + 검색 색인(Pagefind)
npm run serve # http://localhost:4321
npm run dev # 고칠 때마다 다시 빌드 (검색 색인은 build에서만)
dist/는 경로에 상관없이 열려요(링크가 모두 상대 경로예요). 404.html도 만들어요.
스크린샷 다시 찍기
npm run screenshots가 실행 중인 앱에서 정해진 화면을 두 언어, 두 테마로 찍어요. 화면마다 무엇을 열고 누를지는 scripts/screenshots/scenarios/<제품>.mjs에 있고, 버튼 이름은 한국어로 적으면 앱의 영어 번역표(i18n-en.ts)로 영어 화면에서도 찾아요.
npm run screenshots # 전부
npm run screenshots -- galpi --lang ko --theme light # 일부만
npm run screenshots -- mothership --only app,catalog
앱의 주소, 로그인할 사람, 로그인 코드를 읽을 서버 로그는 환경 변수나 docs/.secrets.local.env(커밋하지 않아요)로 줘요: GALPI_URL, GALPI_LOGIN_CODE, MOTHERSHIP_URL, MOTHERSHIP_LOG, NARU_URL, NARU_LOG 등. 데모 데이터를 만드는 법은 docs/README.md에 있어요.
코드가 바뀌었을 때
npm run drift # 확인한 커밋 이후 바뀐 것과, 다시 볼 페이지
npm run drift -- galpi --stat
페이지의 sources:에 적은 파일이나 폴더가 바뀌었으면 그 페이지를 알려 줘요. 다시 확인한 뒤 sources.yaml의 커밋과 날짜를 올려요. sources:는 이 추적에만 쓰고 페이지에는 보이지 않아요.
버전
지금은 버전이 하나(최신)예요. 나눌 때가 오면:
npm run version:cut -- 2026.11 "2026년 11월"
content/, nav.yaml, sources.yaml을 versions/2026.11/에 얼려 두고 versions.yaml에 더해요. 최신은 계속 /에, 얼린 버전은 /v/2026.11/에 나가고, 버전이 둘 이상이면 왼쪽 아래에 버전 고르기가 생겨요. 지난 버전 페이지에는 최신으로 가는 띠가 붙고, 검색은 최신만 찾아요.