logi 개발자 문서 사이트

VitePress + Scalar (OpenAPI UI) 조합.

로컬 개발

패키지 매니저는 pnpm (lockfile: pnpm-lock.yaml).

cd docs-site
pnpm install
pnpm dev          # http://localhost:5173
pnpm build        # .vitepress/dist 생성 (build:llms 포함)
pnpm preview      # 프로덕션 빌드 미리보기

구조

docs-site/
├── .vitepress/config.mts    # 사이드바 + 네비 + 검색
├── public/
│   ├── openapi.yaml         # OpenAPI 3.1 (수기 + 서버 구현 기반)
│   └── icon.svg             # (선택)
├── index.md                 # 랜딩 (Hero + Features)
├── guide/                   # 큐레이트 가이드
│   ├── index.md
│   ├── quickstart.md
│   ├── concepts.md
│   ├── security.md
│   ├── rate-limits.md
│   ├── webhooks.md
│   └── webhook-verification.md
├── oauth/                   # OAuth/OIDC 상세
│   ├── flow.md
│   ├── pkce.md
│   ├── scopes.md
│   ├── jwks.md
│   └── errors.md
├── en/                      # 영문 번역 (frontmatter translation_of + source_hash)
├── integrations/            # 프레임워크 예제
│   ├── nextjs.md
│   ├── rails.md
│   ├── swift.md
│   └── express.md
└── reference/
    ├── api.md               # Scalar UI (openapi.yaml 로드)
    ├── cli.md
    ├── mcp.md
    └── changelog.md

배포

🔴 push 는 배포가 아니다. 자동 배포는 없다. (2026-08-13 실측 확정)

https://docs.1pass.dev 는 카페24 박스(58.121.85.187, Caddy)의 /srv/static/logi-docs 를 서빙합니다. Render 가 아닙니다 — DNS 가 애초에 Render 를 가리키지 않습니다. 배포 단위는 커밋이 아니라 로컬 빌드 산출물 전체 rsync 라, main 이 최신이어도 rsync 를 돌리지 않으면 사이트는 그대로입니다.

# 0. 게시 여부 선판정 — 날짜가 안 움직였으면 미배포다
curl -sI https://docs.1pass.dev/oauth/troubleshooting.html | grep -i last-modified

# 1. 빌드 (origin/main 워크트리에서 — 로컬 브랜치 오염 방지)
pnpm install --frozen-lockfile --config.dangerouslyAllowAllBuilds=true
pnpm build

# 2. 롤백본 → rsync
ssh cafe24 'cp -a /srv/static/logi-docs /srv/static/logi-docs.bak-$(date +%Y%m%d)'
rsync -rlptz --checksum --delete-after -e "ssh -o BatchMode=yes" \
  .vitepress/dist/ cafe24:/srv/static/logi-docs/

# 3. 라이브에서 이번 변경점 실물 확인 (파일 존재가 아니라 내용)
curl -s https://docs.1pass.dev/<바꾼-경로>.html | grep -c "<바꾼-문구>"

절차 정본은 cafe24-deploy 스킬 §1.5. --config.dangerouslyAllowAllBuilds=true 가 없으면 pnpm install 이 ERR_PNPM_IGNORED_BUILDS(esbuild·puppeteer·vue-demi)로 죽습니다.

• 빌드 커맨드: pnpm build (내부에서 build:llms 로 llms.txt ko/en 생성 후 vitepress build)
• 퍼블리시 디렉토리: .vitepress/dist
• i18n:check 는 build 에 물려 있지 않습니다 — STALE 이 쌓여 있어도 빌드는 통과합니다.

⚠️ Render logi-docs 는 라이브가 아니다

Render 에 동명의 정적 사이트(srv-d7nk27d7vvec7395vsrg)가 남아 있지만 suspended + autoDeploy: no 이고, logi-docs.onrender.com 으로만 뜹니다. 여기에 배포해도 docs.1pass.dev 는 바뀌지 않습니다.

이 문서가 예전에 "autodeploy ON" 이라고 적어둔 탓에 2026-08-07~13 사이 문서 변경 3건이 6일간 미게시로 방치됐습니다. 발견이 늦은 이유는 suspend 된 정적 사이트가 404 가 아니라 200 으로 옛 콘텐츠를 계속 서빙하기 때문입니다 — 그래서 위 0단계의 last-modified 확인이 게시 판정의 시작점입니다.

push 전 체크 (i18n)

영문 번역(en/**)은 frontmatter translation_of + source_hash(번역 시점 ko 파일의 git hash-object 값) 계약으로 신선도를 추적합니다. ko 문서를 수정하면 en 페어도 갱신하고 source_hash 를 새로 박아야 합니다:

pnpm i18n:check   # 번역 신선도(STALE/ORPHAN/MISSING) + en 링크 검사
pnpm build        # 빌드 통과 확인

둘 다 green 인 상태로 push 하세요.