@unana_dev/doxen 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,34 +1,136 @@
1
- # Doxen
1
+ # Doxen으로 팀 문서 사이트 10분 만에 만들기
2
2
 
3
- > 기존 저장소의 Markdown 폴더를 설정 파일 하나로 연결하는 npm 패키지입니다. Node.js 22 이상이 필요합니다. 현재 0.2.0 구현 기준입니다.
3
+ > 저장소에 흩어진 Markdown 파일, 그대로 두고 **설정 파일 하나로** 검색 되는 문서 사이트를 만들어 봅시다.
4
+ > 필요하다면 **명령 하나로 우리 팀만 볼 수 있는 비공개 사이트**로 배포까지 할 수 있습니다.
4
5
 
5
- 상단 탭, 폴더별 문서 탐색, 목차, 한국어 전체 검색, 검색 위치 이동, 문서 및 지정 섹션 안에서 찾기 기능을 제공합니다. React/Vue 등 사용자 프로젝트의 프레임워크에 의존하지 않으며, 사이트 소스는 패키지 안에 있습니다.
6
+ ---
6
7
 
7
- ## 설치와 시작
8
+ ## 목차
8
9
 
9
- npm 레지스트리에 배포된 패키지는 다음과 같이 설치합니다. 로컬 설치는 `npm pack`으로 만든 tgz 경로를 패키지명 대신 사용합니다.
10
+ 1. [Doxen이 뭔가요?](#doxen이-뭔가요)
11
+ 2. [시작 전 준비물](#시작-전-준비물)
12
+ 3. [1단계: 설치하기](#1단계-설치하기)
13
+ 4. [2단계: 초기 설정 만들기 (init)](#2단계-초기-설정-만들기-init)
14
+ 5. [3단계: 미리보기 띄우기 (dev)](#3단계-미리보기-띄우기-dev)
15
+ 6. [4단계: 설정 파일 이해하기](#4단계-설정-파일-이해하기)
16
+ 7. [5단계: 문서 작성 규칙](#5단계-문서-작성-규칙)
17
+ 8. [6단계: 정적 사이트로 빌드하기](#6단계-정적-사이트로-빌드하기)
18
+ 9. [7단계: 비공개 사이트로 배포하기 (Cloudflare)](#7단계-비공개-사이트로-배포하기-cloudflare)
19
+ 10. [보너스: AI로 문서 양식 맞추기](#보너스-ai로-문서-양식-맞추기)
20
+ 11. [자주 겪는 문제](#자주-겪는-문제)
21
+ 12. [명령어 한눈에 보기](#명령어-한눈에-보기)
22
+ 13. [Doxen에 기여하고 싶다면](#doxen에-기여하고-싶다면)
23
+
24
+ ---
25
+
26
+ ## Doxen이 뭔가요?
27
+
28
+ Doxen은 **이미 저장소에 있는 Markdown 폴더를 문서 사이트로 바꿔 주는 npm 패키지**입니다.
29
+
30
+ 새 문서 시스템으로 옮길 필요 없이, 지금 있는 폴더를 설정 파일에 연결하기만 하면 됩니다. 만들어지는 사이트에는 이런 기능이 들어 있어요.
31
+
32
+ - 상단 **탭** (예: 시작하기 / 작성 가이드 / 레퍼런스)
33
+ - 폴더별 **문서 탐색** 목록
34
+ - 자동 **목차**
35
+ - **한국어 전체 검색** (⌘/Ctrl + K) 과 검색 위치로 바로 이동
36
+ - 문서 안, 또는 지정한 섹션 안에서만 **찾기**
37
+
38
+ React나 Vue 같은 프레임워크를 프로젝트에 설치할 필요도 없습니다. 사이트를 그리는 코드는 전부 패키지 안에 들어 있어요.
39
+
40
+ ---
41
+
42
+ ## 시작 전 준비물
43
+
44
+ | 준비물 | 확인 방법 |
45
+ | --- | --- |
46
+ | **Node.js 22 이상** | 터미널에서 `node -v` 실행 → `v22.x.x` 이상이면 OK |
47
+ | npm 또는 Yarn | `npm -v` 또는 `yarn -v` |
48
+ | Markdown 문서를 둘 프로젝트 폴더 | 기존 저장소여도, 새 폴더여도 괜찮습니다 |
49
+
50
+ > 💡 Node 버전이 낮다면 [nvm](https://github.com/nvm-sh/nvm) 같은 버전 관리 도구로 22 이상을 설치하세요.
51
+
52
+ 배포까지 하실 계획이라면 **Cloudflare 계정**도 필요합니다. 이건 [7단계](#7단계-비공개-사이트로-배포하기-cloudflare)에서 자세히 다룹니다.
53
+
54
+ ---
55
+
56
+ ## 1단계: 설치하기
57
+
58
+ 문서를 붙일 프로젝트 폴더에서 아래 명령을 실행합니다. 개발용 도구이므로 `-D`(devDependencies)로 설치합니다.
59
+
60
+ **npm을 쓴다면**
10
61
 
11
62
  ```bash
12
63
  npm install -D @unana_dev/doxen
13
- npx docs init
14
- npm run docs:dev
15
- npm run docs:build
16
64
  ```
17
65
 
18
- Yarn도 같은 패키지를 사용할 수 있습니다.
66
+ **Yarn을 쓴다면**
19
67
 
20
68
  ```bash
21
69
  yarn add -D @unana_dev/doxen
70
+ ```
71
+
72
+ ### 💡 `docs`와 `doxen`, 둘 다 같은 명령이에요
73
+
74
+ Doxen은 실행 명령을 두 가지 이름으로 제공합니다.
75
+
76
+ - `docs` — 짧고 편한 이름
77
+ - `doxen` — 다른 패키지와 이름이 겹칠 때 쓰는 이름
78
+
79
+ `docs`라는 이름은 흔해서 다른 의존성과 충돌할 수 있습니다. 그래서 `init`이 만들어 주는 스크립트는 **`doxen`을 사용**합니다. 헷갈리면 그냥 **항상 `doxen`을 쓰셔도 됩니다.**
80
+
81
+ ---
82
+
83
+ ## 2단계: 초기 설정 만들기 (init)
84
+
85
+ ```bash
86
+ npx doxen init
87
+ # 또는
22
88
  yarn doxen init
89
+ ```
90
+
91
+ ### init이 해주는 일
92
+
93
+ 설정 파일이 아직 없다면 다음을 자동으로 준비해 줍니다.
94
+
95
+ - `docs.config.ts` — 사이트 설정 파일
96
+ - `docs/README.md` — 시작용 샘플 문서
97
+ - `package.json`에 스크립트 3개 추가: `docs:dev`, `docs:build`, `docs:deploy`
98
+ - `.gitignore`에 빌드 결과물과 `node_modules` 등록
99
+
100
+ ### 안심하세요: 아무것도 덮어쓰지 않아요
101
+
102
+ `init`은 **기존 설정, 문서, 프로젝트 스크립트를 덮어쓰지 않습니다.** 이미 사용 중인 프로젝트에서 실행해도 안전합니다.
103
+
104
+ > 📁 **이미 문서 폴더가 있다면?**
105
+ > 설정 파일에서 경로만 기존 폴더로 바꿔 주고, 자동 생성된 시작 문서(`docs/README.md`)는 필요 없으면 지우면 됩니다.
106
+
107
+ ---
108
+
109
+ ## 3단계: 미리보기 띄우기 (dev)
110
+
111
+ ```bash
112
+ npm run docs:dev
113
+ # 또는
23
114
  yarn docs:dev
24
- yarn docs:build
25
115
  ```
26
116
 
27
- `docs`라는 실행 파일이 다른 의존성과 겹치면 동일한 CLI인 `doxen`을 사용하세요. 생성되는 스크립트는 충돌을 줄이기 위해 `doxen`을 사용합니다.
117
+ 브라우저에서 **http://127.0.0.1:4173** 을 열어 보세요. 문서 사이트가 보이면 성공입니다! 🎉
28
118
 
29
- `init`은 기존 설정, 문서, 프로젝트 스크립트를 덮어쓰지 않습니다. 설정이 없으면 `docs/README.md`, `docs.config.ts`를 만들고 `docs:dev`, `docs:build`, `docs:deploy` 스크립트를 추가합니다. `.gitignore`에는 생성물과 `node_modules`를 등록합니다. 이미 문서 폴더가 있다면 설정 파일의 경로만 연결하고 생성된 시작 문서는 필요에 따라 제거하세요.
119
+ Markdown 파일을 수정하고 저장하면 **브라우저가 자동으로 새로고침**됩니다.
30
120
 
31
- ## 설정
121
+ **포트를 바꾸고 싶다면** (4173 포트를 이미 다른 프로그램이 쓰고 있을 때 등)
122
+
123
+ ```bash
124
+ npx doxen dev --port 4200
125
+ ```
126
+
127
+ > ⚠️ 로컬 미리보기에는 로그인/인증이 적용되지 않습니다. 배포 후 보호는 7단계에서 다룹니다.
128
+
129
+ ---
130
+
131
+ ## 4단계: 설정 파일 이해하기
132
+
133
+ `docs.config.ts`를 열어 보면 대략 이런 모양입니다.
32
134
 
33
135
  ```ts
34
136
  // docs.config.ts
@@ -36,43 +138,130 @@ export default {
36
138
  title: '팀 문서',
37
139
  icon: { background: '#edf8ff', color: '#467792', border: '#bcdff8' },
38
140
  tabs: [
39
- { title: '시작하기', dir: './guide', slug: 'guide' },
40
- { title: '작성 가이드', dir: './writing', slug: 'writing' },
41
- { title: '레퍼런스', dir: './reference', slug: 'reference' },
141
+ { title: '시작하기', dir: './guide', slug: 'guide' },
142
+ { title: '작성 가이드', dir: './writing', slug: 'writing' },
143
+ { title: '레퍼런스', dir: './reference', slug: 'reference' },
42
144
  ],
43
145
  };
44
146
  ```
45
147
 
46
- 선택적으로 `import { defineConfig } from '@unana_dev/doxen'`을 사용하면 타입 도움을 받을 수 있습니다. `.ts`, `.mjs`, `.js` 설정을 지원합니다. 설정 파일은 Node에서 실행되므로 신뢰할 수 있는 저장소에서 사용하세요.
148
+ > 💡 **자동완성을 받고 싶다면** `defineConfig`를 감싸서 쓰세요. 타입 힌트가 생겨서 오타를 줄일 수 있습니다.
149
+ >
150
+ > ```ts
151
+ > import { defineConfig } from '@unana_dev/doxen';
152
+ >
153
+ > export default defineConfig({
154
+ > title: '팀 문서',
155
+ > tabs: [ /* ... */ ],
156
+ > });
157
+ > ```
47
158
 
48
- - `dir`: 설정 파일 기준의 전용 하위 폴더. 저장소 루트 또는 외부 폴더는 허용하지 않습니다.
49
- - `slug`: 고유한 영문 소문자·숫자·하이픈. 문서 URL의 일부입니다.
50
- - `icon.background` / `icon.color`: 상단 로고와 파비콘의 배경색 / 글자색. `#fff` 또는 `#ffffff` 형식의 HEX 색상을 지원하며, 생략하면 각각 `#edf8ff` / `#467792`가 적용됩니다.
51
- - `icon.border`: 상단 로고의 테두리 색상. 같은 HEX 형식을 지원하며, 기본값은 `#bcdff8`입니다.
52
- - `icon: '#eab308'`처럼 색상 하나만 지정하면 같은 색 계열의 밝은 배경색, 중간 톤 테두리, 진한 글자색을 자동 생성합니다. 개별 색상 객체 대신 사용할 수 있습니다.
53
- - 파일 이름순(숫자 순서 인식)으로 정렬합니다. `01-introduction.md`처럼 번호를 붙이면 순서를 제어할 수 있습니다.
54
- - 하위 폴더는 탐색 목록에 경로로 표시합니다. 숨김 파일, `node_modules`, 심볼릭 링크 문서는 제외합니다.
55
- - 탭 전체 내용은 같은 정적 사이트에 포함됩니다. 탭별 권한 분리는 제공하지 않습니다.
159
+ 설정 파일은 `.ts`, `.mjs`, `.js` 중 아무거나 쓸 수 있습니다.
56
160
 
57
- ## 명령
161
+ ### tabs: 상단 탭 하나 = 문서 폴더 하나
58
162
 
59
- | 명령 | 기능 |
60
- | --- | --- |
61
- | `docs init` | 시작 문서, 설정, 스크립트, Git 제외 설정 |
62
- | `docs dev` | `http://127.0.0.1:4173` 미리보기와 변경 시 자동 새로고침 |
63
- | `docs dev --port 4200` | 포트 변경 |
64
- | `docs build` | 설정 파일 옆 `.docs-dist/`에 정적 사이트 생성 |
65
- | `docs deploy` | 인증 설정 검사 → 빌드 → Cloudflare Pages 운영 배포 |
66
- | `docs build --config ./config/docs.config.ts` | 설정 파일 지정 (dev, deploy, ai에도 적용) |
67
- | `docs ai --file docs/guide.md --instruction "변경 요청"` | 표준 문서 양식과 AI 편집 작업 지침을 stdout에 출력 |
163
+ | 항목 | 의미 | 규칙 |
164
+ | --- | --- | --- |
165
+ | `title` | 상단 탭에 보이는 이름 | 자유롭게 |
166
+ | `dir` | 이 탭에 보여줄 문서 폴더 | **설정 파일 기준 하위 폴더**여야 함 |
167
+ | `slug` | 문서 URL에 들어가는 이름 | **영문 소문자·숫자·하이픈**만, 탭끼리 **겹치면 안 됨** |
168
+
169
+ `dir`에서 자주 하는 실수:
170
+
171
+ ```ts
172
+ dir: './guide' // ✅ 설정 파일 옆의 guide 폴더
173
+ dir: './' // ❌ 저장소 루트는 허용되지 않음
174
+ dir: '../shared' // ❌ 설정 파일 바깥 폴더는 허용되지 않음
175
+ ```
176
+
177
+ `slug`에서 자주 하는 실수:
178
+
179
+ ```ts
180
+ slug: 'getting-started' // ✅
181
+ slug: 'Guide' // ❌ 대문자
182
+ slug: '시작하기' // ❌ 한글
183
+ slug: 'my_docs' // ❌ 밑줄
184
+ ```
185
+
186
+ ### icon: 로고와 파비콘 색상
187
+
188
+ 상단 로고와 브라우저 탭 아이콘(파비콘)의 색을 정합니다. 두 가지 방법이 있어요.
189
+
190
+ **방법 1. 색 하나만 지정 (가장 쉬움)**
191
+
192
+ ```ts
193
+ icon: '#eab308',
194
+ ```
195
+
196
+ 이 색을 기준으로 밝은 배경색, 중간 톤 테두리, 진한 글자색을 **알아서** 만들어 줍니다.
197
+
198
+ **방법 2. 하나하나 직접 지정**
199
+
200
+ ```ts
201
+ icon: {
202
+ background: '#edf8ff', // 배경색 (생략 시 #edf8ff)
203
+ color: '#467792', // 글자색 (생략 시 #467792)
204
+ border: '#bcdff8', // 로고 테두리 (생략 시 #bcdff8)
205
+ },
206
+ ```
207
+
208
+ 색상은 `#fff` 또는 `#ffffff` 형식의 **HEX 값**만 지원합니다.
209
+
210
+ ### 문서 정렬 순서
211
+
212
+ 탐색 목록은 **파일 이름순**으로 정렬됩니다. 숫자도 똑똑하게 인식해서 `2`가 `10`보다 앞에 옵니다. 순서를 정하고 싶다면 파일 이름 앞에 번호를 붙이세요.
213
+
214
+ ```
215
+ guide/
216
+ ├── 01-introduction.md
217
+ ├── 02-installation.md
218
+ ├── 03-first-page.md
219
+ └── advanced/
220
+ └── 01-config.md
221
+ ```
222
+
223
+ - 하위 폴더는 탐색 목록에 **경로 형태로** 표시됩니다.
224
+ - 숨김 파일(`.`으로 시작), `node_modules`, 심볼릭 링크 문서는 **제외**됩니다.
225
+
226
+ > ⚠️ **보안 메모**
227
+ > - 설정 파일은 Node에서 **실제로 실행되는 코드**입니다. 신뢰할 수 있는 저장소에서만 사용하세요.
228
+ > - 모든 탭은 **하나의 사이트에 함께** 들어갑니다. "이 탭은 A팀만 보기" 같은 탭별 권한은 없습니다.
229
+
230
+ ---
231
+
232
+ ## 5단계: 문서 작성 규칙
233
+
234
+ ### 그대로 쓸 수 있는 것 ✅
235
+
236
+ - 표준 Markdown (제목, 목록, 강조 등)
237
+ - 코드 블록, 표
238
+ - 다른 문서로의 상대 링크 (`[설치 방법](./02-installation.md)`)
239
+ - 한국어 제목 앵커 (`#설치-방법`)
240
+ - 이미지·PDF 첨부: PNG / JPEG / GIF / WebP / AVIF / ICO / PDF
241
+
242
+ ### 지원하지 않는 것 ❌
243
+
244
+ - 실행 가능한 HTML (HTML을 쓰면 **실행되지 않고 글자로** 보입니다)
245
+ - MDX
246
+ - YAML frontmatter (문서 맨 위 `---` 메타데이터)
247
+ - 확장 Markdown 플러그인
68
248
 
69
- 빌드는 자체 생성 표시가 있는 출력 폴더만 교체합니다. 문서 변환에 실패하면 이전 성공 결과를 유지합니다. 출력에는 문서 HTML과 검색용 본문이 포함되므로 소스가 비공개라면 결과물도 비공개로 배포해야 합니다.
249
+ ### 빌드가 실패하는 경우 🚨
70
250
 
71
- ## 검색과 문서 작성
251
+ 이 두 가지는 **빌드를 멈추게** 하니 꼭 기억해 두세요.
72
252
 
73
- `⌘/Ctrl K` 또는 상단 검색 버튼으로 모든 탭의 제목·본문·표·코드를 검색합니다. 공백으로 나눈 단어를 모두 포함하는 섹션을 찾으며 제목에 일치하는 결과를 먼저 표시합니다. 한국어 Unicode 정규화와 영문 대소문자 구분 없는 부분 일치를 지원합니다. 형태소 분석·오타 교정 검색은 포함하지 않습니다.
253
+ 1. **존재하지 않는 `.md` 파일로 링크했을 때** — 파일 이름 오타를 잡아 줍니다.
254
+ 2. **문서 폴더 밖의 파일을 첨부했을 때** — 이미지는 문서 폴더 안에 두세요.
74
255
 
75
- 결과를 선택하면 해당 문서와 제목 위치로 이동하며 일치하는 글자를 표시합니다. 문서 상단 검색창 또는 다음과 같은 섹션 검색창에서 이전·다음 버튼, Enter / Shift+Enter로 이동합니다. 검색은 현재 선택한 한 영역에 적용됩니다. 섹션 및 문서 내 검색은 입력한 문자열이 포함된 표의 본문 행만 남기고 나머지 행을 숨깁니다. 표 머리글은 유지하며 검색어를 지우면 모든 행을 복원합니다. 영문 대소문자와 한국어 Unicode 정규화를 적용하고 앞뒤 공백을 제외한 연속 문자열로 비교합니다. 표 밖의 본문은 숨기지 않고 일치 위치를 강조합니다.
256
+ > 💡 링크 대상 파일은 검사하지만, 그 안의 **제목 앵커(`#어떤-제목`)가 실제로 있는지는 검사하지 않습니다.** 앵커 링크는 직접 눌러서 확인해 주세요.
257
+
258
+ ### 목차는 자동으로
259
+
260
+ 문서의 제목들이 자동으로 목차에 나타납니다. 같은 제목이 여러 번 나오면 앵커에 `-1`, `-2`가 붙습니다.
261
+
262
+ ### 섹션 안에서만 검색하기: `:::search`
263
+
264
+ 표가 긴 섹션에는 **그 섹션 전용 검색창**을 달 수 있습니다. 제목 **바로 아래**에 `:::search 영역 이름`을 쓰고, 끝에 `:::`로 닫으면 됩니다.
76
265
 
77
266
  ```markdown
78
267
  ## 1. 문서 작성
@@ -82,116 +271,311 @@ export default {
82
271
  | 작업 | 방법 |
83
272
  | --- | --- |
84
273
  | 제목 추가 | Markdown 제목 문법 사용 |
274
+ | 링크 추가 | 상대 경로 .md 링크 사용 |
85
275
  :::
86
276
  ```
87
277
 
88
- 번호가 있는 제목은 검색 영역 밖에 두세요. 제목 바로 아래에 `:::search 영역 이름`을 작성하면 해당 영역에만 검색창이 표시됩니다. 검색이 필요 없는 섹션은 일반 Markdown으로 작성합니다. 기존처럼 검색 영역 안에 첫 제목을 작성한 문서도 화면에서는 제목 아래로 검색창을 배치합니다. 전체 검색은 헤더 중앙, 문서 전체에서 찾기는 본문 상단의 접이식 메뉴로 제공합니다.
278
+ 이렇게 하면 해당 영역에 검색창이 생기고, 검색어가 들어 있는 **표의 행만 남기고 나머지는 숨겨** 줍니다. (표 머리글은 그대로, 검색어를 지우면 모두 복원)
279
+
280
+ 작성할 때 지킬 것:
89
281
 
90
- 표준 Markdown, 코드 블록, 표, 상대 `.md` 링크, 한국어 제목 앵커, 이미지와 PDF 첨부를 지원합니다. 연결된 PNG/JPEG/GIF/WebP/AVIF/ICO/PDF만 복사하며 문서 폴더 밖 첨부는 빌드 오류로 처리합니다. 로컬 파일 링크는 현재 문서 기준 상대 경로를 사용하세요. 한 문서의 여러 검색 영역을 나란히 구성할 수 있으며 중첩 검색 영역은 사용하지 마세요.
282
+ - **번호가 있는 제목(`## 1. ...`)은 `:::search` 바깥**, 바로 위에 두세요.
283
+ - 한 문서에 검색 영역을 **여러 개 나란히** 둘 수 있습니다.
284
+ - 검색 영역 **안에 또 검색 영역을 넣지(중첩) 마세요.**
285
+ - 검색이 필요 없는 섹션은 그냥 평범한 Markdown으로 쓰면 됩니다.
91
286
 
92
- 제목은 자동으로 목차에 표시됩니다. 중복 제목에는 `-1`, `-2`가 붙습니다. Markdown 링크가 존재하지 않는 문서 파일을 가리키면 빌드를 중단합니다. 대상 제목 앵커의 존재 여부는 별도로 검사하지 않습니다.
287
+ ### 검색은 이렇게 동작해요
93
288
 
94
- 실행 가능한 HTML, MDX, YAML frontmatter 메타데이터, 확장 Markdown 플러그인은 현재 지원하지 않습니다. 원시 HTML은 실행하지 않고 텍스트로 표시하며 결과 HTML을 정제합니다. 외부 이미지·링크는 원래 URL을 유지합니다.
289
+ | 종류 | 어디서 | 특징 |
290
+ | --- | --- | --- |
291
+ | **전체 검색** | 헤더 중앙, ⌘/Ctrl + K | 모든 탭의 제목·본문·표·코드 검색. 띄어쓴 단어를 **모두 포함**한 섹션을 찾고, 제목 일치를 먼저 보여 줌 |
292
+ | **문서 내 찾기** | 본문 상단 접이식 메뉴 | 현재 문서 안에서 찾기 |
293
+ | **섹션 검색** | `:::search` 영역 | 해당 섹션 안에서만 찾기 |
95
294
 
96
- ## AI로 정해진 양식에 맞추기
295
+ - 영문은 대소문자를 구분하지 않습니다.
296
+ - 한국어는 유니코드 정규화를 적용해서 비교합니다.
297
+ - 결과 사이 이동: 이전/다음 버튼, **Enter / Shift+Enter**
298
+ - 형태소 분석이나 오타 교정은 **하지 않습니다.** ("설치했다"로 "설치"를 찾는 식의 검색은 안 되니, 짧은 핵심 단어로 검색하세요.)
299
+
300
+ ---
301
+
302
+ ## 6단계: 정적 사이트로 빌드하기
97
303
 
98
304
  ```bash
99
- npx docs ai --file guide/writing.md --instruction "현재 내용을 유지하고 문서 작성 방법을 표로 정리" > /tmp/writing-prompt.txt
305
+ npm run docs:build
306
+ # 또는
307
+ yarn docs:build
100
308
  ```
101
309
 
102
- 생성된 내용을 사용 중인 AI 코딩 도구에 전달하세요. 문서 정보 범위 → 번호별 단계 → 예외 → 관련 문서 순서의 양식과 기존 문서, 요청을 함께 제공합니다. 결과를 검토하여 Markdown에 반영한 다음 미리보기와 Git diff를 확인합니다.
310
+ 설정 파일 옆의 **`.docs-dist/`** 폴더에 완성된 정적 사이트가 생깁니다. 이 폴더를 원하는 정적 호스팅에 올리면 끝!
103
311
 
104
- 이 명령은 API를 호출하거나 파일을 자동 수정하지 않습니다. AI 제공자·모델·인증 설정이 정해지지 않아 현재 버전은 도구에 전달할 작업 지침 생성까지 제공합니다. 출력에 기존 문서 전문이 포함되므로 공유 범위는 원본 문서와 동일하게 취급하세요.
312
+ 알아 두면 좋은 점:
105
313
 
106
- ## 명령 하나로 비공개 배포하기
314
+ - Doxen이 만든 표시가 있는 출력 폴더만 교체하니, 다른 폴더를 실수로 지울 걱정은 없습니다.
315
+ - 문서 변환에 실패하면 **이전에 성공한 결과를 그대로 유지**합니다.
316
+ - 사이트는 해시 URL(`#/...`)을 써서, `example.com/docs/` 같은 **하위 경로에 올려도 서버 설정 없이** 동작합니다.
107
317
 
108
- 문서 프로젝트에서 다음 명령을 실행하세요. 최초에는 한국어 설정 안내가 나오고, 이후에는 같은 명령으로 수정한 문서를 다시 배포합니다. Node.js 22 이상이 필요하며 Wrangler는 Doxen에 포함되어 별도로 설치하지 않습니다.
318
+ 설정 파일 위치가 기본과 다르다면 `--config`로 지정하세요. (`dev`, `deploy`, `ai` 명령에도 똑같이 쓸 수 있습니다.)
319
+
320
+ ```bash
321
+ npx doxen build --config ./config/docs.config.ts
322
+ ```
323
+
324
+ > ⚠️ **비공개 문서라면 주의!**
325
+ > 빌드 결과에는 문서 HTML과 **검색용 본문 전체**가 들어 있습니다. 원본이 비공개라면 결과물도 반드시 **비공개로** 배포하세요. 가장 쉬운 방법이 바로 다음 단계입니다.
326
+
327
+ ---
328
+
329
+ ## 7단계: 비공개 사이트로 배포하기 (Cloudflare)
330
+
331
+ 사내 문서처럼 **허락된 사람만** 봐야 하는 경우, Doxen은 Cloudflare Pages + Cloudflare Access를 이용해 **명령 하나로** 비공개 배포를 해 줍니다.
109
332
 
110
333
  ```bash
111
334
  npx doxen deploy
112
335
  # 또는 npm run docs:deploy / yarn docs:deploy
113
336
  ```
114
337
 
115
- 문서 설정이 아직 없다면 먼저 `npx doxen init`으로 문서 폴더를 준비하세요. 기존 프로젝트도 `init`을 다시 실행하면 배포 스크립트가 추가됩니다. `--config ./config/docs.config.ts`로 다른 문서 설정을 지정할 수 있습니다.
338
+ - 처음 실행하면 **한국어 안내**를 따라 설정을 진행합니다.
339
+ - 두 번째부터는 같은 명령으로 **수정한 문서를 다시 배포**합니다.
340
+ - Wrangler(Cloudflare CLI)는 Doxen에 포함되어 있어서 **따로 설치할 필요 없습니다.**
341
+
342
+ > 이미 Doxen을 쓰던 프로젝트라 `docs:deploy` 스크립트가 없다면, `npx doxen init`을 한 번 더 실행하세요. 다른 것은 건드리지 않고 배포 스크립트만 추가됩니다.
343
+
344
+ ### 7-1. 배포 전에 직접 해야 하는 일
116
345
 
117
- ### 첫 실행에서 하는 일
346
+ 자동화가 많이 되어 있지만, 아래 세 가지는 **본인이 직접** 해야 합니다.
118
347
 
119
- 1. **Cloudflare 연결:** 안내되는 [토큰 발급 화면](https://dash.cloudflare.com/profile/api-tokens)에서 로그인하고 배포용 API 토큰을 한 번 발급합니다. 터미널의 가려진 입력란에 붙여넣습니다. 환경 변수를 직접 설정할 필요는 없습니다.
120
- 2. **계정 선택:** 접근 가능한 계정을 조회합니다. 여러 개면 사용할 계정을 선택합니다.
121
- 3. **사이트 이름과 열람자 입력:** 새 사이트 이름과 열람할 업무 이메일을 입력합니다. 본인 이메일도 포함하세요. 기존 회사 로그인 방법이 있으면 선택하고, 없으면 이메일 일회용 코드 로그인을 준비합니다.
122
- 4. **내용 확인:** 계정·사이트·열람자·업로드할 문서 폴더를 확인하고 진행합니다.
123
- 5. **자동 준비와 배포:** Pages 프로젝트, 운영·미리보기 Access 애플리케이션, 허용 이메일 정책, Fail closed 설정을 준비하고 검증합니다. AUD와 팀 주소도 자동으로 가져옵니다. 이후 문서를 빌드하고 업로드합니다.
348
+ - [ ] **Cloudflare 계정** 만들기
349
+ - [ ] Zero Trust를 처음 쓰는 계정이라면 **약관 동의와 플랜 선택** (Doxen은 유료 플랜을 구매하지 않습니다)
350
+ - [ ] **API 토큰 발급** (아래 권한 참고)
124
351
 
125
- Cloudflare 계정 생성, 토큰 발급 및 계정에서 요구하는 Zero Trust 최초 약관·플랜 선택은 사용자가 진행해야 합니다. 도구는 유료 플랜을 구매하지 않습니다. 토큰에는 사용할 **계정 하나**를 지정하고 다음 권한을 부여하세요. 일반 Wrangler 브라우저 로그인만으로 이 Access 자동 설정을 대신하지 않습니다.
352
+ #### API 토큰 권한
126
353
 
127
- | Account 권한 | 수준 | 용도 |
354
+ 토큰을 만들 때 **사용할 계정 하나만** 지정하고, 아래 4가지 **Account 권한**을 주세요.
355
+
356
+ | Account 권한 | 수준 | 왜 필요한가요? |
128
357
  | --- | --- | --- |
129
358
  | Account Settings | Read | 계정 조회 |
130
359
  | Cloudflare Pages | Edit | 프로젝트 생성·배포 |
131
360
  | Access: Apps and Policies | Edit | 접근 애플리케이션·허용 정책 생성·조회 |
132
- | Access: Organizations, Identity Providers, and Groups | Edit | 팀 주소 확인·생성 및 로그인 방법 준비 |
361
+ | Access: Organizations, Identity Providers, and Groups | Edit | 팀 주소 확인·생성, 로그인 방법 준비 |
362
+
363
+ > ⚠️ 평소 쓰는 `wrangler login`(브라우저 로그인)만으로는 Access 자동 설정을 할 수 없습니다. **반드시 위 권한의 API 토큰**이 필요해요.
364
+
365
+ ### 7-2. 첫 실행 흐름
366
+
367
+ `npx doxen deploy`를 처음 실행하면 다음 순서로 진행됩니다.
368
+
369
+ 1. **Cloudflare 연결**
370
+ 안내되는 토큰 발급 화면에서 로그인해 토큰을 발급하고, 터미널의 입력란에 붙여넣습니다. (입력 내용은 화면에 가려져 보이지 않는 게 정상이에요.) 환경 변수를 직접 설정할 필요는 없습니다.
371
+
372
+ 2. **계정 선택**
373
+ 접근 가능한 계정을 조회합니다. 여러 개라면 사용할 계정을 고릅니다.
374
+
375
+ 3. **사이트 이름과 열람자 입력**
376
+ 새 사이트 이름과, 문서를 볼 사람들의 업무 이메일을 입력합니다.
377
+ 👉 **본인 이메일도 꼭 넣으세요!** 안 넣으면 본인도 못 봅니다.
378
+ 회사 로그인 방법(SSO 등)이 이미 있다면 그걸 고르고, 없으면 **이메일 일회용 코드 로그인**이 준비됩니다.
379
+
380
+ 4. **내용 확인**
381
+ 계정·사이트·열람자·업로드할 문서 폴더를 확인하고 진행합니다.
382
+
383
+ 5. **자동 준비 & 배포**
384
+ Pages 프로젝트, 운영·미리보기용 Access 애플리케이션, 허용 이메일 정책, Fail closed 설정까지 만들고 검증한 뒤, 문서를 빌드해서 업로드합니다.
385
+
386
+ 배포가 끝나면 꼭 **확인**해 보세요.
387
+
388
+ - [ ] 허용한 이메일로 로그인 → 문서와 첨부파일이 열리는지
389
+ - [ ] 허용하지 않은 이메일로 로그인 → 막히는지
390
+ - [ ] **운영 주소**와 **미리보기 주소** 둘 다 확인
391
+
392
+ > 실제 계정 로그인과 정책 전파는 자동 테스트로 검증할 수 없어서, 이 확인은 직접 하셔야 합니다.
393
+
394
+ ### 7-3. 다음부터는 이 명령 하나
395
+
396
+ 문서를 고쳤다면:
397
+
398
+ ```bash
399
+ npx doxen deploy
400
+ ```
401
+
402
+ 사이트 이름이나 이메일을 다시 묻지 않고, 기존 정책을 확인한 뒤 바로 운영에 배포합니다. **Git push도 필요 없습니다.**
403
+
404
+ ### 7-4. 열람자 추가·삭제하기
405
+
406
+ 배포 설정은 설정 파일 옆 **`.doxen-deploy.json`** 에 저장됩니다. 열람자를 바꾸려면 이 파일의 `emails`만 고치고 다시 배포하세요.
407
+
408
+ ```json
409
+ "emails": ["member@company.com", "new-member@company.com"]
410
+ ```
411
+
412
+ ```bash
413
+ npx doxen deploy
414
+ ```
415
+
416
+ 운영·미리보기 양쪽 정책에 자동으로 반영됩니다.
417
+
418
+ 꼭 알아 둘 점:
419
+
420
+ - **이 JSON 목록이 기준**입니다. Cloudflare 대시보드에서만 추가한 이메일은 다음 배포 때 **지워집니다.**
421
+ - 이메일을 지워도 **이미 로그인한 세션은 바로 끊기지 않습니다.** 즉시 차단하려면 Cloudflare에서 활성 세션도 취소하세요.
422
+ - 이전 배포에는 당시 이메일 목록이 남아 있습니다. 필요하면 이전 배포도 삭제하세요. **롤백하면 이전 목록이 돌아올 수 있습니다.**
423
+ - Doxen이 만든 정책 외에 별도 정책·그룹·보안 조건이 있으면, 덮어쓰지 않고 **중단**합니다.
424
+ - 허용된 사람은 **사이트 전체**를 봅니다. 문서별·탭별 권한은 없습니다.
425
+
426
+ ### 7-5. 토큰은 어디에 저장되나요?
427
+
428
+ | 환경 | 동작 |
429
+ | --- | --- |
430
+ | macOS / Linux | 저장할지 물어봅니다. 저장하면 `~/.config/doxen/accounts/<계정 ID>.json`에 **평문**으로 저장 (폴더 700, 파일 600 권한). OS 키체인은 아닙니다. |
431
+ | Windows | 자동 저장 없음 → 매번 입력 |
133
432
 
134
- 기존 회사 로그인 설정은 변경하지 않고 선택한 방법을 사용합니다. 로그인 방법이 없는 계정에는 확인 화면에 안내한 대로 이메일 일회용 코드 제공자를 추가합니다. 기존 Pages 프로젝트와 이름이 충돌하면 다른 이름을 선택해야 하며, 기존 사이트를 자동으로 인수하거나 덮어쓰지 않습니다.
433
+ - 토큰이 만료되거나 권한이 거부되면 새 토큰을 입력하라고 안내합니다.
434
+ - 컴퓨터에서 토큰을 지우려면 위 계정 파일을 삭제하세요.
435
+ - **토큰 자체를 무효화**하려면 Cloudflare에서 토큰을 폐기해야 합니다.
135
436
 
136
- ### 다음 배포와 저장 위치
437
+ `.doxen-deploy.json`에는 계정 ID, 사이트, 허용 이메일, Access 식별자가 들어가고 **API 토큰은 들어가지 않습니다.** 다만 팀 저장소에 커밋할 때는 **이메일 목록이 노출돼도 괜찮은지** 확인하세요.
137
438
 
138
- Markdown 수정 후 **같은 `npx doxen deploy` 명령**을 실행하세요. 설정이 완료되어 있으면 사이트 이름·이메일을 다시 묻지 않습니다. 기존 정책과 Fail closed 설정을 확인한 다음 운영 브랜치에 배포합니다. Git push는 필요하지 않습니다.
439
+ ### 7-6. CI에서 배포하기
139
440
 
140
- - 프로젝트 설정은 문서 설정 파일 옆 `.doxen-deploy.json`에 저장합니다. 계정 ID, 사이트, 허용 이메일과 생성된 Access 식별자가 들어가며 API 토큰은 들어가지 않습니다. 기존 `docs.config.ts`를 수정하지 않습니다. 팀 저장소에 공유할 때는 이메일 목록의 공개 범위를 확인하세요.
141
- - macOS/Linux에서는 토큰을 이 컴퓨터에 저장할지 선택할 수 있습니다. 저장하면 `~/.config/doxen/accounts/<계정 ID>.json`에 **평문으로 저장**하며 디렉터리는 700, 파일은 600 권한을 사용합니다. OS 키체인 저장은 아닙니다. 저장하지 않으면 다음 실행에서 다시 입력합니다. Windows에서는 자동 저장을 제공하지 않습니다.
142
- - 저장된 토큰이 만료되거나 계정 권한이 거부되면 새 토큰 입력을 안내합니다. 토큰을 제거하려면 해당 계정 파일을 삭제하고, 효력을 없애려면 Cloudflare에서 토큰을 폐기하세요.
143
- - CI에서는 저장된 프로젝트 설정과 비밀 환경 변수 `CLOUDFLARE_API_TOKEN`을 사용합니다. `CLOUDFLARE_ACCOUNT_ID`를 함께 지정할 경우 저장된 계정과 같아야 합니다. 대화형 최초 설정은 CI에서 실행하지 않습니다.
441
+ CI(GitHub Actions 등)에서는 대화형 첫 설정을 할 수 없습니다. 그래서 순서는 이렇습니다.
144
442
 
145
- 중간에 실패하면 생성된 자원의 식별자를 보존합니다. 같은 명령을 다시 실행하면 기록된 단계에서 이어갑니다. 설정이 미완료된 동안에는 일반 `docs build`도 차단합니다. 서버가 자원을 만들었지만 응답·로컬 기록에 실패한 경우에는 중복 생성이나 기존 사이트 덮어쓰기를 막기 위해 대시보드 확인이 필요할 수 있습니다. 자동으로 원격 자원을 삭제하지 않습니다.
443
+ 1. **로컬에서** `npx doxen deploy`로 첫 설정을 끝내고 `.doxen-deploy.json`을 저장소에 둡니다.
444
+ 2. CI의 비밀 환경 변수에 `CLOUDFLARE_API_TOKEN`을 등록합니다.
445
+ 3. CI에서 `npx doxen deploy`를 실행합니다.
146
446
 
147
- ### 열람 권한과 운영 관리
447
+ `CLOUDFLARE_ACCOUNT_ID`도 지정한다면 저장된 계정 ID와 **같아야** 합니다.
148
448
 
149
- 배포 이력·롤백·도메인은 Cloudflare Pages, 로그인·접근 정책은 Cloudflare One의 Access에서 관리합니다. 자동 설정은 기본 Pages 운영 주소와 미리보기 주소를 대상으로 합니다. 커스텀 도메인은 별도로 연결하고 Access로 보호해야 합니다.
449
+ ### 7-7. 중간에 실패했다면?
150
450
 
151
- 새 열람자는 **운영·미리보기 Access 정책과 `.doxen-deploy.json`의 `emails`에 모두 추가**한 뒤 재배포합니다. 도구는 재배포 때 정책을 임의로 덮어쓰지 않고 목록의 일치를 검사합니다. 퇴사자 등의 접근을 회수할 때는 모든 관련 Access 정책에서 제거하고 활성 세션을 취소한 다음 저장된 목록도 수정해 재배포하세요. 이전 배포에는 당시 목록이 남으므로 필요하면 이전 배포도 삭제합니다. 롤백하면 이전 목록도 돌아올 수 있습니다.
451
+ **같은 명령을 다시 실행하세요.** 이미 만든 자원의 식별자를 기억하고 있어서, 멈춘 단계부터 이어서 진행합니다.
152
452
 
153
- 허용 사용자는 사이트 전체를 읽습니다. 문서별·탭별 권한은 제공하지 않습니다. 자동 설정은 초기 연결 과정을 줄이는 기능이며, 별도의 열람자 관리 화면은 아직 없습니다.
453
+ - 설정이 끝나지 않은 동안에는 일반 `docs build`도 막힙니다. (보호 없는 빌드가 실수로 나가는 걸 방지)
454
+ - Doxen은 원격 자원을 **자동으로 삭제하지 않습니다.**
455
+ - 드물게 서버에는 자원이 생겼는데 응답을 못 받은 경우, 중복 생성을 막기 위해 Cloudflare 대시보드를 직접 확인해야 할 수 있습니다.
456
+ - 같은 이름의 Pages 프로젝트가 이미 있으면 **다른 이름**을 골라야 합니다. 기존 사이트를 가져가거나 덮어쓰지 않습니다.
154
457
 
155
- ### 보호 방식과 기존 수동 설정
458
+ ### 7-8. 보호는 어떻게 동작하나요? (궁금한 분만)
156
459
 
157
- 배포 설정이 있으면 `docs build`에도 Pages 서버 인증 코드(`_worker.js`)와 전체 경로 라우팅(`_routes.json`)이 포함됩니다. 서버는 Cloudflare Access JWT의 서명·발급자·AUD·만료와 허용 이메일을 확인한 뒤 파일을 제공합니다. HTML, `/site.json`, 이미지, PDF 모두 보호하며 인증 실패·공개키 조회 실패는 403으로 차단합니다. 응답은 `private, no-store`로 설정합니다. Cache Rules로 이를 덮어쓰지 마세요.
460
+ 배포 설정이 있으면 빌드 결과에 Pages 서버 인증 코드(`_worker.js`)와 라우팅 설정(`_routes.json`)이 함께 들어갑니다. 서버는 요청마다 Cloudflare Access의 JWT(서명·발급자·AUD·만료)와 허용 이메일을 확인한 뒤에만 파일을 내줍니다.
158
461
 
159
- 로그인은 Cloudflare Access가 담당합니다. Access가 연결되지 않은 주소는 로그인 화면 대신 403을 반환합니다. 배포 후 허용·미허용 계정으로 운영·미리보기 주소의 문서와 첨부파일 접근을 확인하세요. 실제 계정의 로그인과 정책 전파는 로컬 자동 테스트로 검증할 수 없습니다.
462
+ - HTML, `/site.json`, 이미지, PDF **전부** 보호됩니다.
463
+ - 인증에 실패하면 **403**으로 차단합니다.
464
+ - 응답은 `private, no-store`로 캐시되지 않게 설정됩니다. **Cache Rules로 이걸 덮어쓰지 마세요.**
160
465
 
161
- 로컬 `docs dev`에는 인증이 적용되지 않습니다. 배포 설정 없는 `docs build`는 일반 정적 사이트를 만듭니다. 보호된 빌드도 일반 정적 호스팅에서는 인증 코드가 실행되지 않으므로 Pages Functions로 배포해야 합니다.
466
+ 주의할 점:
162
467
 
163
- 기존 `docs.config.ts`의 `deploy` 설정과 환경 변수 방식도 지원합니다. 자동 설정 파일과 수동 `deploy` 설정을 동시에 두지는 마세요. 수동 설정은 기존처럼 호스트별 Access 정책과 Fail closed를 관리자가 준비해야 합니다.
468
+ - 이 보호는 **Cloudflare Pages(Functions)** 에서만 동작합니다. 같은 빌드를 일반 정적 호스팅에 올리면 인증 코드가 실행되지 않습니다.
469
+ - 자동 설정은 기본 Pages 운영 주소와 미리보기 주소만 보호합니다. **커스텀 도메인**은 직접 연결하고 Access로 보호해야 합니다.
470
+ - 배포 이력·롤백·도메인은 **Cloudflare Pages**에서, 로그인·접근 정책은 **Cloudflare One의 Access**에서 관리합니다.
471
+
472
+ ### 7-9. 수동 설정을 쓰던 분이라면
473
+
474
+ `docs.config.ts`에 직접 `deploy` 설정을 넣는 기존 방식도 계속 지원합니다.
164
475
 
165
476
  ```ts
166
477
  deploy: {
167
478
  project: 'team-docs',
168
479
  access: {
169
480
  teamDomain: 'https://your-team.cloudflareaccess.com',
170
- audiences: ['0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'],
481
+ audiences: ['0123456789abcdef...'],
171
482
  emails: ['member@company.com'],
172
483
  },
173
484
  },
174
485
  ```
175
486
 
176
- 공식 참고: [Pages 프로젝트 생성 API](https://developers.cloudflare.com/api/resources/pages/subresources/projects/methods/create/), [Access 애플리케이션 API](https://developers.cloudflare.com/api/resources/zero_trust/subresources/access/subresources/applications/methods/create/), [Zero Trust 조직 API](https://developers.cloudflare.com/api/resources/zero_trust/subresources/organizations/methods/create/), [JWT 검증](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/), [Fail closed](https://developers.cloudflare.com/pages/functions/routing/).
487
+ 이 경우 호스트별 Access 정책과 Fail closed는 관리자가 직접 준비해야 합니다. **`.doxen-deploy.json`(자동)과 수동 `deploy` 설정을 동시에 두지는 마세요.**
488
+
489
+ ---
490
+
491
+ ## 보너스: AI로 문서 양식 맞추기
492
+
493
+ 팀 문서의 형식을 통일하고 싶을 때, Doxen이 **AI 코딩 도구에 붙여넣을 작업 지침**을 만들어 줍니다.
494
+
495
+ ```bash
496
+ npx doxen ai --file guide/writing.md \
497
+ --instruction "현재 내용을 유지하고 문서 작성 방법을 표로 정리" \
498
+ > /tmp/writing-prompt.txt
499
+ ```
500
+
501
+ 생성된 파일에는 표준 양식(**문서 정보 범위 → 번호별 단계 → 예외 → 관련 문서**), 기존 문서 내용, 요청이 함께 들어 있습니다.
502
+
503
+ 사용 순서:
504
+
505
+ 1. 위 명령으로 지침 파일을 만든다.
506
+ 2. 내용을 사용 중인 AI 코딩 도구에 전달한다.
507
+ 3. 결과를 검토해서 Markdown에 반영한다.
508
+ 4. 미리보기와 `git diff`로 확인한다.
509
+
510
+ > 이 명령은 **AI API를 호출하지도, 파일을 고치지도 않습니다.** 지침 텍스트를 출력할 뿐이에요.
511
+ > 출력에는 기존 문서 전문이 포함되니, **원본 문서와 같은 공유 범위**로 다뤄 주세요.
512
+
513
+ ---
514
+
515
+ ## 자주 겪는 문제
516
+
517
+ **Q. `docs` 명령이 이상하게 동작해요.**
518
+ 다른 패키지의 `docs` 명령과 이름이 겹쳤을 수 있어요. `npx doxen ...`을 사용하세요.
519
+
520
+ **Q. 파일을 고쳐도 미리보기가 갱신되지 않아요. / `EMFILE`, `ENOSPC` 에러가 나요.**
521
+ 파일 감시 한도에 걸렸거나 네트워크 파일시스템을 쓰는 경우입니다. 폴링 모드로 실행하세요.
522
+
523
+ ```bash
524
+ CHOKIDAR_USEPOLLING=1 npm run docs:dev
525
+ ```
526
+
527
+ **Q. 빌드가 링크 오류로 멈춰요.**
528
+ 존재하지 않는 `.md` 파일로 링크했거나, 문서 폴더 밖의 파일을 첨부한 경우입니다. 터미널 메시지에 나온 경로를 확인하세요. 로컬 파일 링크는 **현재 문서 기준 상대 경로**로 써야 합니다.
529
+
530
+ **Q. 설정 오류가 났어요.**
531
+ 오류 내용은 터미널과 미리보기 화면에 함께 표시됩니다. 고친 뒤 새로고침하면 복구됩니다. `dir`이 하위 폴더인지, `slug`가 영문 소문자·숫자·하이픈인지 먼저 확인해 보세요.
532
+
533
+ **Q. 배포한 사이트가 로그인 화면 대신 403만 보여요.**
534
+ 그 주소에 Access가 연결되어 있지 않은 경우입니다. 특히 **커스텀 도메인**이라면 Access로 직접 보호해야 합니다.
535
+
536
+ **Q. 이메일을 지웠는데 그 사람이 아직 볼 수 있어요.**
537
+ 기존 로그인 세션이 남아 있는 겁니다. Cloudflare에서 해당 사용자의 활성 세션을 취소하세요.
538
+
539
+ **Q. 문서가 아주 많은데 괜찮을까요?**
540
+ 사이트가 전체 문서 데이터를 한 번에 내려받는 구조라, 현재는 **소규모~중규모 팀 문서**에 맞춰져 있습니다. 대형 저장소는 성능을 미리 확인해 보세요.
541
+
542
+ ---
543
+
544
+ ## 명령어 한눈에 보기
545
+
546
+ | 하고 싶은 일 | 명령 |
547
+ | --- | --- |
548
+ | 처음 세팅 | `npx doxen init` |
549
+ | 미리보기 (http://127.0.0.1:4173) | `npm run docs:dev` |
550
+ | 미리보기 포트 변경 | `npx doxen dev --port 4200` |
551
+ | 정적 사이트 빌드 (`.docs-dist/`) | `npm run docs:build` |
552
+ | 비공개 배포 / 재배포 | `npx doxen deploy` |
553
+ | 다른 설정 파일 사용 | `--config ./config/docs.config.ts` (dev, build, deploy, ai 공통) |
554
+ | AI 작업 지침 생성 | `npx doxen ai --file <문서> --instruction "<요청>"` |
555
+
556
+ ---
557
+
558
+ ## Doxen에 기여하고 싶다면
177
559
 
178
- ## 패키지 개발·검증·게시
560
+ 패키지 자체를 개발하거나 검증하려면 Doxen 저장소에서 다음 명령을 사용합니다.
179
561
 
180
562
  ```bash
181
563
  npm ci
182
- npm run dev # 예제 사이트
183
- npm run check # Node 테스트와 문법 검사
184
- npm run test:browser # Chromium 브라우저 테스트
185
- npm run test:package # tgz를 별도 프로젝트에 설치하여 검증
186
- npm run build # 예제 정적 빌드
187
- npm pack --dry-run # 배포 파일 목록 검토
564
+ npm run dev # 예제 사이트 실행
565
+ npm run check # Node 테스트 + 문법 검사
566
+ npm run test:browser # Chromium 브라우저 테스트
567
+ npm run test:package # tgz를 별도 프로젝트에 설치해서 검증
568
+ npm run build # 예제 정적 빌드
569
+ npm pack --dry-run # 배포될 파일 목록 확인
188
570
  npm pack
189
571
  ```
190
572
 
191
- 브라우저 테스트는 먼저 `npx playwright install chromium`을 실행하세요. 기존 Chrome을 쓰려면 `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`에 실행 파일 경로를 설정할 수 있습니다. npm에 게시하려면 스코프 소유권·이름 사용 가능 여부·로그인을 확인한 뒤 버전을 갱신하고 `npm publish --access public`을 실행합니다. 게시 여부는 이 저장소 구현 완료와 별개입니다.
573
+ - 브라우저 테스트 전에 `npx playwright install chromium`을 먼저 실행하세요. 이미 설치된 Chrome을 쓰려면 `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`에 실행 파일 경로를 지정하면 됩니다.
574
+ - 로컬에서 만든 패키지를 다른 프로젝트에 설치해 보려면, `npm pack`으로 만든 `.tgz` 경로를 패키지 이름 대신 넣어 설치하세요.
575
+ - npm 배포 파일은 `bin/`, `src/`, `client/`, README, LICENSE로 제한됩니다. 예제·테스트는 포함되지 않습니다.
192
576
 
193
- 배포 파일은 package.json의 `files` 허용 목록으로 제한됩니다. `bin/`, `src/`, `client/`, README, LICENSE만 포함하고 예제, 테스트, 문서 저장소 원본은 포함하지 않습니다. 런타임 의존성은 일반 npm 의존성으로 설치합니다.
577
+ **구조 한 줄 요약:** `bin/docs.js` → 설정 로더 → Markdown·섹션·첨부 처리 → 정적 빌드 또는 로컬 서버. 화면과 브라우저 검색 코드는 `client/`에 있습니다.
194
578
 
195
- 구조: `bin/docs.js` → 설정 로더 → Markdown/섹션/첨부 처리 → 정적 빌드 또는 로컬 서버. 화면과 브라우저 검색은 `client/`에 있습니다. 사이트는 해시 URL을 사용해 하위 경로에서도 서버 rewrite 없이 동작합니다. 전체 문서 데이터를 한 번 내려받으므로 초기 버전은 소규모·중규모 팀 문서에 맞췄으며 대형 저장소 성능은 별도 측정이 필요합니다.
579
+ ---
196
580
 
197
- 파일 감시 한도 오류(EMFILE/ENOSPC)나 네트워크 파일시스템에서 갱신이 안 되면 `CHOKIDAR_USEPOLLING=1 npm run docs:dev`를 사용하세요. 설정·문서 오류는 터미널과 미리보기 응답에 표시되며 수정 후 새로고침하면 복구됩니다.
581
+ 궁금한 점이나 버그는 저장소 이슈로 남겨 주세요. 즐거운 문서 작성 되세요! 📚
package/bin/docs.js CHANGED
@@ -19,7 +19,7 @@ try {
19
19
  },
20
20
  });
21
21
  const [command, ...extra] = positionals;
22
- if (values.version) console.log("0.2.0");
22
+ if (values.version) console.log("0.2.1");
23
23
  else if (values.help || !command)
24
24
  console.log(
25
25
  `Doxen — 저장소 기반 문서 사이트\n\n docs init 설정과 스크립트 생성\n docs dev [--port 4173] 로컬 미리보기 및 자동 갱신\n docs build .docs-dist 정적 사이트 생성\n docs deploy 최초 설정 안내 및 비공개 Cloudflare Pages 배포\n docs ai --file <문서.md> --instruction "변경 요청"\n 표준 양식과 AI 작업 지침을 stdout으로 출력\n\n옵션: --config <파일> (dev/build/deploy/ai), --help, --version\n동일 명령: doxen <명령>`,
package/client/app.js CHANGED
@@ -54,60 +54,45 @@ function highlight(root, query) {
54
54
  return hits;
55
55
  }
56
56
 
57
- let finders = [];
58
- function attachFinder(input, root, count, prev, next) {
59
- const rows = [...root.querySelectorAll("tbody tr")];
60
- let hits = [];
61
- let index = -1;
62
- const state = {
63
- input,
64
- reset() {
65
- for (const row of rows) row.hidden = false;
66
- hits = [];
67
- index = -1;
68
- count.textContent = "";
69
- prev.disabled = next.disabled = true;
70
- },
71
- };
72
- finders.push(state);
73
- const update = () => {
74
- count.textContent = input.value
75
- ? `${index < 0 ? 0 : index + 1} / ${hits.length}`
76
- : "";
77
- prev.disabled = next.disabled = !hits.length;
78
- };
79
- const move = (direction) => {
80
- if (!hits.length) return;
81
- hits[index]?.classList.remove("active-hit");
82
- index = (index + direction + hits.length) % hits.length;
83
- hits[index].classList.add("active-hit");
84
- hits[index].scrollIntoView({ block: "center", behavior: "smooth" });
85
- update();
86
- };
87
- input.oninput = () => {
88
- for (const finder of finders)
89
- if (finder !== state) {
90
- finder.input.value = "";
91
- finder.reset();
92
- }
93
- clearMarks($("#article"));
94
- for (const row of rows) {
95
- row.hidden = !matchesRow([...row.cells].map((cell) => cell.textContent).join(" "), input.value);
96
- }
97
- hits = highlight(root, input.value);
98
- index = -1;
99
- if (hits.length) move(1);
100
- else update();
101
- };
102
- input.onkeydown = (event) => {
103
- if (event.key === "Enter") {
104
- event.preventDefault();
105
- move(event.shiftKey ? -1 : 1);
57
+ function attachTableSearches() {
58
+ const article = $("#article");
59
+ const labels = new Map();
60
+ for (const section of article.querySelectorAll(".search-section")) {
61
+ labels.set(section, section.querySelector(".section-tools label")?.textContent);
62
+ section.querySelector(".section-tools")?.remove();
63
+ }
64
+ let heading = current.title;
65
+ let index = 0;
66
+ for (const node of article.querySelectorAll("h1, h2, h3, h4, h5, h6, table")) {
67
+ if (node.tagName !== "TABLE") {
68
+ heading = node.textContent;
69
+ continue;
106
70
  }
107
- };
108
- prev.onclick = () => move(-1);
109
- next.onclick = () => move(1);
110
- state.reset();
71
+ const table = node;
72
+ const tools = el("div", undefined, "section-tools");
73
+ const id = `table-search-${index++}`;
74
+ const label = el(
75
+ "label",
76
+ labels.get(table.closest(".search-section")) || `${heading} 표 검색`,
77
+ );
78
+ label.htmlFor = id;
79
+ const input = el("input");
80
+ input.id = id;
81
+ input.type = "search";
82
+ input.dataset.tableSearch = "";
83
+ input.placeholder = "표 안에서 검색";
84
+ const rows = [...table.querySelectorAll("tbody tr")];
85
+ input.oninput = () => {
86
+ clearMarks(table);
87
+ for (const row of rows)
88
+ row.hidden = !matchesRow(
89
+ [...row.cells].map((cell) => cell.textContent).join(" "),
90
+ input.value,
91
+ );
92
+ };
93
+ tools.append(label, input);
94
+ table.before(tools);
95
+ }
111
96
  }
112
97
 
113
98
  function renderNavigation() {
@@ -161,9 +146,6 @@ function render() {
161
146
  renderNavigation();
162
147
  $("#toc").replaceChildren();
163
148
  $("#pagination").replaceChildren();
164
- $("#page-search").value = "";
165
- finders = [];
166
- $(".document-find").open = false;
167
149
  if (!current) {
168
150
  $("#article").replaceChildren(
169
151
  el(
@@ -177,13 +159,11 @@ function render() {
177
159
  "설정된 폴더에 Markdown 파일을 추가하거나 왼쪽 목록에서 문서를 선택하세요.",
178
160
  ),
179
161
  );
180
- $(".document-tools").hidden = true;
181
162
  $("#breadcrumb").textContent = site.tabs.find(
182
163
  (tab) => tab.slug === activeTab,
183
164
  ).title;
184
165
  return;
185
166
  }
186
- $(".document-tools").hidden = false;
187
167
  document.title = `${current.title} · ${site.title}`;
188
168
  $("#breadcrumb").textContent =
189
169
  `${site.tabs.find((tab) => tab.slug === current.tab).title} / ${current.path}`;
@@ -216,25 +196,9 @@ function render() {
216
196
  link.append(el("small", label), el("strong", doc.title));
217
197
  $("#pagination").append(link);
218
198
  }
219
- attachFinder(
220
- $("#page-search"),
221
- $("#article"),
222
- $("#page-count"),
223
- $("#page-prev"),
224
- $("#page-next"),
225
- );
226
- for (const section of document.querySelectorAll(".search-section"))
227
- attachFinder(
228
- section.querySelector("[data-section-search]"),
229
- section.querySelector(".section-content"),
230
- section.querySelector(".match-count"),
231
- section.querySelector("[data-find-prev]"),
232
- section.querySelector("[data-find-next]"),
233
- );
199
+ attachTableSearches();
234
200
  if (pendingQuery) {
235
- $(".document-find").open = true;
236
- $("#page-search").value = pendingQuery;
237
- $("#page-search").oninput();
201
+ highlight($("#article"), pendingQuery);
238
202
  pendingQuery = "";
239
203
  }
240
204
  if (anchor) {
package/client/index.html CHANGED
@@ -12,7 +12,7 @@
12
12
  <a class="skip-link" href="#content">본문으로 이동</a>
13
13
  <header>
14
14
  <a class="brand" href="#/" aria-label="문서 홈"
15
- ><span class="brand-icon">S</span
15
+ ><span class="brand-icon">D</span
16
16
  ><span id="site-title">Doxen</span></a
17
17
  ><button id="open-search" class="search-trigger">
18
18
  <span>⌕ &nbsp; 검색...</span><kbd>⌘ / Ctrl K</kbd></button
@@ -27,19 +27,6 @@
27
27
  </aside>
28
28
  <main id="content" tabindex="-1">
29
29
  <div id="breadcrumb"></div>
30
- <details class="document-find">
31
- <summary>이 문서에서 찾기</summary>
32
- <div class="document-tools">
33
- <label for="page-search">이 문서에서 찾기</label
34
- ><input
35
- id="page-search"
36
- type="search"
37
- placeholder="검색어 입력"
38
- /><span id="page-count" aria-live="polite"></span
39
- ><button id="page-prev" aria-label="이전 일치">↑</button
40
- ><button id="page-next" aria-label="다음 일치">↓</button>
41
- </div>
42
- </details>
43
30
  <article id="article"></article>
44
31
  <nav id="pagination" aria-label="이전 다음 문서"></nav>
45
32
  </main>
package/client/style.css CHANGED
@@ -197,59 +197,9 @@ main {
197
197
  #breadcrumb {
198
198
  color: #46a5df;
199
199
  font-size: 11px;
200
- padding-right: 135px;
201
200
  margin-bottom: 12px;
202
201
  overflow-wrap: anywhere;
203
202
  }
204
- .document-find {
205
- position: absolute;
206
- right: 0;
207
- top: 28px;
208
- z-index: 1;
209
- font-size: 11px;
210
- color: #8a929c;
211
- }
212
- .document-find > summary {
213
- cursor: pointer;
214
- list-style: none;
215
- border: 1px solid var(--line);
216
- padding: 3px 9px;
217
- border-radius: 6px;
218
- background: white;
219
- }
220
- .document-tools {
221
- position: absolute;
222
- right: 0;
223
- top: 34px;
224
- width: 330px;
225
- display: flex;
226
- gap: 5px;
227
- align-items: center;
228
- background: white;
229
- border: 1px solid var(--line);
230
- padding: 10px;
231
- border-radius: 9px;
232
- box-shadow: 0 5px 20px #122c4115;
233
- }
234
- .document-tools label {
235
- position: absolute;
236
- clip-path: inset(50%);
237
- width: 1px;
238
- height: 1px;
239
- overflow: hidden;
240
- }
241
- .document-tools input {
242
- width: 130px;
243
- flex: 1;
244
- font-size: 12px;
245
- padding: 5px 8px;
246
- }
247
- .document-tools span {
248
- white-space: nowrap;
249
- }
250
- .document-tools button {
251
- padding: 2px 7px;
252
- }
253
203
  article {
254
204
  font-size: 14px;
255
205
  line-height: 1.85;
@@ -407,17 +357,6 @@ article img {
407
357
  border-radius: 3px;
408
358
  font-size: 12px;
409
359
  }
410
- .section-tools button {
411
- padding: 0 6px;
412
- border: 0;
413
- }
414
- .section-tools button:disabled {
415
- display: none;
416
- }
417
- .match-count {
418
- white-space: nowrap;
419
- color: #8794a1;
420
- }
421
360
  .section-content > :first-child {
422
361
  margin-top: 12px;
423
362
  }
@@ -475,10 +414,6 @@ mark {
475
414
  color: inherit;
476
415
  border-radius: 2px;
477
416
  }
478
- mark.active-hit {
479
- background: #ffe17c;
480
- outline: 1px solid #d5ad39;
481
- }
482
417
  .skip-link {
483
418
  position: absolute;
484
419
  left: -999px;
@@ -598,9 +533,6 @@ dialog::backdrop {
598
533
  main {
599
534
  padding-top: 25px;
600
535
  }
601
- .document-find {
602
- top: 22px;
603
- }
604
536
  article h1 {
605
537
  font-size: 27px;
606
538
  }
@@ -617,9 +549,6 @@ dialog::backdrop {
617
549
  #breadcrumb {
618
550
  font-size: 10px;
619
551
  }
620
- .document-tools {
621
- width: min(330px, calc(100vw - 40px));
622
- }
623
552
  .section-tools {
624
553
  padding: 6px 9px;
625
554
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unana_dev/doxen",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Config-first Markdown documentation sites with Korean and section search",
5
5
  "type": "module",
6
6
  "bin": {
package/src/build.js CHANGED
@@ -25,12 +25,16 @@ export async function siteFiles(config, dev = false) {
25
25
  files.set(
26
26
  "/favicon.svg",
27
27
  Buffer.from(
28
- `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="${config.icon.background}"/><text x="16" y="17" dominant-baseline="central" text-anchor="middle" font-family="Arial, sans-serif" font-size="22" font-weight="700" fill="${config.icon.color}">${initial.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)}</text></svg>`,
28
+ `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="${config.icon.background}"/><text x="16" y="16" dominant-baseline="middle" text-anchor="middle" font-family="Arial, sans-serif" font-size="22" font-weight="700" fill="${config.icon.color}">${initial.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)}</text></svg>`,
29
29
  ),
30
30
  );
31
31
  for (const name of ["index.html", "app.js", "style.css", "search.js"])
32
32
  files.set(`/${name}`, await readFile(path.join(client, name)));
33
33
  let html = files.get("/index.html").toString();
34
+ html = html.replace(
35
+ '<span class="brand-icon">D</span',
36
+ `<span class="brand-icon">${initial.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)}</span`,
37
+ );
34
38
  html = html.replace(
35
39
  "</head>",
36
40
  `<style>:root{--icon-background:${config.icon.background};--icon-color:${config.icon.color};--icon-border:${config.icon.border}}</style></head>`,
package/src/content.js CHANGED
@@ -82,7 +82,7 @@ export async function collectSite(config) {
82
82
  const label =
83
83
  tokens[index].info.trim().slice(6).trim() || "이 섹션 검색";
84
84
  const id = `section-search-${searchIndex++}`;
85
- return `<section class="search-section"><div class="section-tools"><label for="${id}">${escape(label)}</label><input id="${id}" type="search" data-section-search placeholder="섹션 안에서 찾기"/><span class="match-count" aria-live="polite"></span><button type="button" data-find-prev aria-label="이전 일치">↑</button><button type="button" data-find-next aria-label="다음 일치">↓</button></div><div class="section-content">`;
85
+ return `<section class="search-section"><div class="section-tools"><label for="${id}">${escape(label)}</label><input id="${id}" type="search" data-section-search placeholder="표 안에서 검색"/></div><div class="section-content">`;
86
86
  },
87
87
  });
88
88
  const tokens = md.parse(doc.source, {});
@@ -7,7 +7,7 @@ const tokenUrl = "https://dash.cloudflare.com/profile/api-tokens";
7
7
  const accountPattern = /^[a-f0-9]{32}$/i;
8
8
  const projectPattern = /^[a-z0-9][a-z0-9-]{0,57}[a-z0-9]$/;
9
9
  export const parseEmails = (text) => [...new Set(text.split(/[\s,;]+/).filter(Boolean).map((email) => email.toLowerCase()))];
10
- const validEmails = (emails) => emails.length > 0 && emails.every((email) => /^[^\s@*]+@[^\s@*]+\.[^\s@*]+$/.test(email));
10
+ const validEmails = (emails) => emails.length > 0 && emails.every((email) => typeof email === "string" && /^[^\s@*]+@[^\s@*]+\.[^\s@*]+$/.test(email));
11
11
 
12
12
  export async function terminalPrompts() {
13
13
  if (!process.stdin.isTTY || !process.stdout.isTTY)
@@ -52,8 +52,6 @@ export async function provision(config, state, api, log = console.log) {
52
52
  if (!provider && state.providerId) throw new Error("선택한 로그인 방법이 삭제되었습니다. Cloudflare One에서 확인하세요.");
53
53
  if (!provider) {
54
54
  provider = providers.find((item) => item.type === "onetimepin");
55
- if (!provider && providers.length)
56
- throw new Error("기존 회사 로그인 설정이 발견되었습니다. npx doxen deploy를 다시 실행해 사용할 로그인 방법을 선택하세요.");
57
55
  if (!provider) provider = await api.send(`${base}/access/identity_providers`, "POST", { name: "Doxen 이메일 인증", type: "onetimepin", config: {} });
58
56
  state.providerId = provider.id;
59
57
  await persist();
@@ -71,13 +69,17 @@ export async function provision(config, state, api, log = console.log) {
71
69
  state.apps[kind] = { id: app.id, aud: app.aud };
72
70
  await persist();
73
71
  }
74
- await verifySetup(state, api);
72
+ await verifySetup(state, api, { syncEmails: true, log });
75
73
  state.ready = true;
76
74
  await persist();
77
75
  return validateDeployment(deploymentFromState(state));
78
76
  }
79
77
 
80
- export async function verifySetup(state, api) {
78
+ export async function verifySetup(state, api, { syncEmails = false, log = console.log } = {}) {
79
+ if (!Array.isArray(state.emails) || !validEmails(state.emails))
80
+ throw new Error("emails에 허용할 이메일을 하나 이상 입력하세요.");
81
+ const desired = [...new Set(state.emails.map((email) => email.toLowerCase()))];
82
+ const updates = [];
81
83
  const base = `/accounts/${state.accountId}`;
82
84
  for (const [kind, domain] of [["production", state.hostname], ["preview", `*.${state.hostname}`]]) {
83
85
  const saved = state.apps[kind];
@@ -92,10 +94,34 @@ export async function verifySetup(state, api) {
92
94
  const policy = policies[0];
93
95
  const actual = policy?.include?.map((rule) => Object.keys(rule).length === 1 ? rule.email?.email?.toLowerCase() : undefined);
94
96
  if (policies.length !== 1 || policy.decision !== "allow" || !actual ||
95
- actual.length !== state.emails.length || actual.some((email) => !state.emails.includes(email)) ||
96
- new Set(actual).size !== state.emails.length)
97
- throw new Error("허용 이메일 정책이 변경되었거나 확인되지 않았습니다. Cloudflare 정책과 .doxen-deploy.json의 emails를 일치시킨 뒤 다시 실행하세요.");
97
+ !validEmails(actual))
98
+ throw new Error("허용 이메일 정책이 변경되었거나 확인되지 않았습니다. Doxen의 단일 이메일 Allow 정책만 자동 관리합니다.");
99
+ const same = actual.length === desired.length && new Set(actual).size === desired.length &&
100
+ actual.every((email) => desired.includes(email));
101
+ if (same) continue;
102
+ if (!syncEmails)
103
+ throw new Error("허용 이메일 정책이 아직 로컬 emails와 일치하지 않습니다. 같은 배포 명령으로 다시 시도하세요.");
104
+ // Do not replace reusable policies or discard manually added security conditions.
105
+ if (policy.name !== "Doxen 열람자" || !/^[\da-f-]{36}$/i.test(policy.id) ||
106
+ policy.reusable === true || policy.app_count > 1 || policy.require?.length ||
107
+ policy.exclude?.length || policy.approval_required || policy.approval_groups?.length ||
108
+ policy.purpose_justification_required || policy.connection_rules)
109
+ throw new Error("허용 이메일 정책에 별도 조건이 설정되어 자동 수정할 수 없습니다. 기존 보안 설정을 확인하세요.");
110
+ const body = {
111
+ name: policy.name, decision: "allow",
112
+ include: desired.map((email) => ({ email: { email } })),
113
+ };
114
+ for (const key of ["precedence", "session_duration", "isolation_required", "mfa_config"])
115
+ if (policy[key] !== undefined) body[key] = policy[key];
116
+ updates.push({ route: `${route}/policies/${policy.id}`, body });
98
117
  }
118
+ // Validate both applications before changing either. Retrying repairs a partial update.
119
+ for (const update of updates) {
120
+ log("JSON의 허용 이메일 목록을 Cloudflare 정책에 반영합니다.");
121
+ await api.send(update.route, "PUT", update.body);
122
+ }
123
+ if (updates.length) await verifySetup(state, api);
124
+
99
125
  }
100
126
 
101
127
  export async function prepareDeployment(config, {
@@ -141,7 +167,7 @@ export async function prepareDeployment(config, {
141
167
  const credentials = { ...env, CLOUDFLARE_ACCOUNT_ID: account, CLOUDFLARE_API_TOKEN: token };
142
168
  if (config.deploy && !state) return { config, env: credentials };
143
169
  if (state?.ready) {
144
- await verifySetup(state, api);
170
+ await verifySetup(state, api, { syncEmails: true, log });
145
171
  return { config: { ...config, deploy: validateDeployment(deploymentFromState(state)) }, env: credentials };
146
172
  }
147
173
  const ask = await ui();
@@ -160,9 +186,21 @@ export async function prepareDeployment(config, {
160
186
  // Read before mutation so an existing company login is preserved.
161
187
  const organization = await api.get(`/accounts/${account}/access/organizations`, { missing: true });
162
188
  const providers = organization ? await api.list(`/accounts/${account}/access/identity_providers`) : [];
163
- if (!state.providerId && providers.length) state.providerId = await ask.select({
164
- message: "열람자가 사용할 로그인 방법", choices: providers.map((item) => ({ name: item.name, value: item.id })),
165
- });
189
+ if (!state.providerId && providers.length) {
190
+ const otp = providers.find((item) => item.type === "onetimepin");
191
+ state.providerId = await ask.select({
192
+ message: "열람자가 사용할 로그인 방법",
193
+ choices: [
194
+ { name: "이메일 일회용 코드 (허용 이메일로 인증)", value: otp?.id || "" },
195
+ ...providers.filter((item) => item.type !== "onetimepin").map((item) => ({
196
+ name: item.type === "cloudflare"
197
+ ? `${item.name || "Cloudflare"} (Cloudflare 계정 필요 · 계정 멤버 제한 가능)`
198
+ : item.name || item.type,
199
+ value: item.id,
200
+ })),
201
+ ],
202
+ });
203
+ }
166
204
  log(`계정: ${account}\n사이트: ${state.project}\n열람자: ${state.emails.join(", ")}\n로그인: ${state.providerId ? "선택한 기존 로그인" : "이메일 일회용 코드 (계정에 로그인 방법 추가)"}\n문서 폴더: ${config.tabs.map((tab) => tab.dir).join(", ")}`);
167
205
  if (!await ask.confirm({ message: "이 설정으로 접근 제한을 준비하고 문서를 배포할까요?", default: true }))
168
206
  throw new Error("배포를 취소했습니다. 문서는 업로드하지 않았습니다.");