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

배포

Render 정적 사이트 logi-docs (https://docs.1pass.dev) — autodeploy ON: main 브랜치에 push 하면 자동으로 빌드·배포됩니다 (별도 트리거 불필요 — 수동 트리거 시 중복 deploy cancel 만 발생).

• rootDir: docs-site
• 빌드 커맨드: pnpm build (내부에서 build:llms 로 llms.txt ko/en 생성 후 vitepress build)
• 퍼블리시 디렉토리: .vitepress/dist

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 하세요.