이 문서 만들기와 고치기

이 사이트는 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/ 빌드, 미리보기 서버, 스크린샷, 변경 추적, 버전 나누기

쓰기

markdown
---
title: 페이지 제목
nav_title: 목록에 보일 짧은 이름 (선택)
description: 제목 아래 한두 문장
sources:                     # 이 페이지가 기대는 소스 (변경 추적에 써요)
  - galpi:docs/설치와-설정.md
  - galpi:apps/server/src/config.ts
keywords: [설치 방법, 배포]   # 본문에 없지만 사람들이 찾을 말 (검색에만 쓰고 보이지 않아요)
---

본문은 Markdown이에요. 다른 페이지는 언어 없이 /galpi/install/ 처럼 적어요.

![스크린샷 설명](shot:galpi/chat)

::: tip 제목(선택)
note, tip, warning, danger 상자
:::

::: steps
1. 번호가 붙은 단계
:::
  • 사이트 안 링크는 언어와 버전이 저절로 붙고, 빌드가 없는 페이지를 가리키는 링크를 찾아 실패시켜요.
  • shot: 이미지는 그 언어의 스크린샷을 쓰고, 없으면 다른 언어의 것을, 그것도 없으면 자리 표시를 보여 줘요. 밝게·어둡게가 둘 다 있으면 테마에 맞춰 바뀌어요.
  • 두 언어의 같은 경로 파일이 서로의 번역이에요. 한쪽만 고치지 않아요.
  • 검색(Pagefind)은 쓴 그대로 못 찾으면 갈피의 채팅 검색과 같은 규칙으로 다시 찾아요. 한국어 조사·어미를 떼고, "어떻게" 같은 물음의 말을 빼고, 그래도 없으면 오른쪽 단어부터 하나씩 빼요(theme/assets/site.js). 본문에 없는 말로 자주 찾는 페이지에는 keywords:를 적어요.

빌드와 미리보기

bash
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)로 영어 화면에서도 찾아요.

bash
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에 있어요.

코드가 바뀌었을 때

bash
npm run drift            # 확인한 커밋 이후 바뀐 것과, 다시 볼 페이지
npm run drift -- galpi --stat

페이지의 sources:에 적은 파일이나 폴더가 바뀌었으면 그 페이지를 알려 줘요. 다시 확인한 뒤 sources.yaml의 커밋과 날짜를 올려요. sources:는 이 추적에만 쓰고 페이지에는 보이지 않아요.

버전

지금은 버전이 하나(최신)예요. 나눌 때가 오면:

bash
npm run version:cut -- 2026.11 "2026년 11월"

content/, nav.yaml, sources.yaml을 versions/2026.11/에 얼려 두고 versions.yaml에 더해요. 최신은 계속 /에, 얼린 버전은 /v/2026.11/에 나가고, 버전이 둘 이상이면 왼쪽 아래에 버전 고르기가 생겨요. 지난 버전 페이지에는 최신으로 가는 띠가 붙고, 검색은 최신만 찾아요.

Esc