@unana_dev/doxen 0.2.4 → 0.2.5

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
@@ -3,8 +3,6 @@
3
3
  > 저장소에 흩어진 Markdown 파일, 그대로 두고 **설정 파일 하나로** 검색 되는 문서 사이트를 만들어 봅시다.
4
4
  > 필요하다면 **명령 하나로 우리 팀만 볼 수 있는 비공개 사이트**로 배포까지 할 수 있습니다.
5
5
 
6
- ---
7
-
8
6
  ## 목차
9
7
 
10
8
  1. [Doxen이 뭔가요?](#doxen이-뭔가요)
@@ -21,8 +19,6 @@
21
19
  12. [명령어 한눈에 보기](#명령어-한눈에-보기)
22
20
  13. [Doxen에 기여하고 싶다면](#doxen에-기여하고-싶다면)
23
21
 
24
- ---
25
-
26
22
  ## Doxen이 뭔가요?
27
23
 
28
24
  Doxen은 **이미 저장소에 있는 Markdown 폴더를 문서 사이트로 바꿔 주는 npm 패키지**입니다.
@@ -37,8 +33,6 @@ Doxen은 **이미 저장소에 있는 Markdown 폴더를 문서 사이트로 바
37
33
 
38
34
  React나 Vue 같은 프레임워크를 프로젝트에 설치할 필요도 없습니다. 사이트를 그리는 코드는 전부 패키지 안에 들어 있어요.
39
35
 
40
- ---
41
-
42
36
  ## 시작 전 준비물
43
37
 
44
38
  | 준비물 | 확인 방법 |
@@ -78,8 +72,6 @@ Doxen은 실행 명령을 두 가지 이름으로 제공합니다.
78
72
 
79
73
  `docs`라는 이름은 흔해서 다른 의존성과 충돌할 수 있습니다. 그래서 `init`이 만들어 주는 스크립트는 **`doxen`을 사용**합니다. 헷갈리면 그냥 **항상 `doxen`을 쓰셔도 됩니다.**
80
74
 
81
- ---
82
-
83
75
  ## 2단계: 초기 설정 만들기 (init)
84
76
 
85
77
  ```bash
@@ -104,8 +96,6 @@ yarn doxen init
104
96
  > 📁 **이미 문서 폴더가 있다면?**
105
97
  > 설정 파일에서 경로만 기존 폴더로 바꿔 주고, 자동 생성된 시작 문서(`docs/README.md`)는 필요 없으면 지우면 됩니다.
106
98
 
107
- ---
108
-
109
99
  ## 3단계: 미리보기 띄우기 (dev)
110
100
 
111
101
  ```bash
@@ -126,8 +116,6 @@ npx doxen dev --port 4200
126
116
 
127
117
  > ⚠️ 로컬 미리보기에는 로그인/인증이 적용되지 않습니다. 배포 후 보호는 7단계에서 다룹니다.
128
118
 
129
- ---
130
-
131
119
  ## 4단계: 설정 파일 이해하기
132
120
 
133
121
  `docs.config.ts`를 열어 보면 대략 이런 모양입니다.
@@ -183,6 +171,16 @@ slug: '시작하기' // ❌ 한글
183
171
  slug: 'my_docs' // ❌ 밑줄
184
172
  ```
185
173
 
174
+ ### color: 사이트 강조색
175
+
176
+ `docs.config.ts`에서 색상 하나를 지정하면 활성 탭, 문서 탐색과 링크, 컴포넌트의 포커스·호버, 인라인 코드와 검색 하이라이팅에 적용됩니다. 배경과 테두리는 해당 색상의 밝은 톤으로 자동 생성합니다.
177
+
178
+ ```ts
179
+ color: '#7e22ce',
180
+ ```
181
+
182
+ `#fff` 또는 `#ffffff` 형식의 HEX 색상을 사용하세요. `icon`을 생략하면 로고와 파비콘에도 같은 색상을 적용합니다. `color` 없이 `icon: '#eab308'`처럼 단일 색상을 지정해도 사이트 강조색에 반영됩니다. 둘 다 지정하면 사이트 강조색은 `color`를 따르고, 로고와 파비콘은 `icon`을 따릅니다. `icon` 객체만 지정하거나 색상 설정을 생략하면 기존 사이트 테마를 유지합니다.
183
+
186
184
  ### icon: 로고와 파비콘 색상
187
185
 
188
186
  상단 로고와 브라우저 탭 아이콘(파비콘)의 색을 정합니다. 두 가지 방법이 있어요.
@@ -227,8 +225,6 @@ guide/
227
225
  > - 설정 파일은 Node에서 **실제로 실행되는 코드**입니다. 신뢰할 수 있는 저장소에서만 사용하세요.
228
226
  > - 모든 탭은 **하나의 사이트에 함께** 들어갑니다. "이 탭은 A팀만 보기" 같은 탭별 권한은 없습니다.
229
227
 
230
- ---
231
-
232
228
  ## 5단계: 문서 작성 규칙
233
229
 
234
230
  ### 그대로 쓸 수 있는 것 ✅
@@ -298,8 +294,6 @@ guide/
298
294
  - 결과 사이 이동: 이전/다음 버튼, **Enter / Shift+Enter**
299
295
  - 형태소 분석이나 오타 교정은 **하지 않습니다.** ("설치했다"로 "설치"를 찾는 식의 검색은 안 되니, 짧은 핵심 단어로 검색하세요.)
300
296
 
301
- ---
302
-
303
297
  ## 6단계: 정적 사이트로 빌드하기
304
298
 
305
299
  ```bash
@@ -325,8 +319,6 @@ npx doxen build --config ./config/docs.config.ts
325
319
  > ⚠️ **비공개 문서라면 주의!**
326
320
  > 빌드 결과에는 문서 HTML과 **검색용 본문 전체**가 들어 있습니다. 원본이 비공개라면 결과물도 반드시 **비공개로** 배포하세요. 가장 쉬운 방법이 바로 다음 단계입니다.
327
321
 
328
- ---
329
-
330
322
  ## 7단계: 비공개 사이트로 배포하기 (Cloudflare)
331
323
 
332
324
  사내 문서처럼 **허락된 사람만** 봐야 하는 경우, Doxen은 Cloudflare Pages + Cloudflare Access를 이용해 **명령 하나로** 비공개 배포를 해 줍니다.
@@ -540,8 +532,6 @@ CHOKIDAR_USEPOLLING=1 npm run docs:dev
540
532
  **Q. 문서가 아주 많은데 괜찮을까요?**
541
533
  사이트가 전체 문서 데이터를 한 번에 내려받는 구조라, 현재는 **소규모~중규모 팀 문서**에 맞춰져 있습니다. 대형 저장소는 성능을 미리 확인해 보세요.
542
534
 
543
- ---
544
-
545
535
  ## 명령어 한눈에 보기
546
536
 
547
537
  | 하고 싶은 일 | 명령 |
@@ -554,8 +544,6 @@ CHOKIDAR_USEPOLLING=1 npm run docs:dev
554
544
  | 다른 설정 파일 사용 | `--config ./config/docs.config.ts` (dev, build, deploy, ai 공통) |
555
545
  | AI 작업 지침 생성 | `npx doxen ai --file <문서> --instruction "<요청>"` |
556
546
 
557
- ---
558
-
559
547
  ## Doxen에 기여하고 싶다면
560
548
 
561
549
  패키지 자체를 개발하거나 검증하려면 Doxen 저장소에서 다음 명령을 사용합니다.
@@ -577,6 +565,4 @@ npm pack
577
565
 
578
566
  **구조 한 줄 요약:** `bin/docs.js` → 설정 로더 → Markdown·섹션·첨부 처리 → 정적 빌드 또는 로컬 서버. 화면과 브라우저 검색 코드는 `client/`에 있습니다.
579
567
 
580
- ---
581
-
582
568
  궁금한 점이나 버그는 저장소 이슈로 남겨 주세요. 즐거운 문서 작성 되세요! 📚
package/client/style.css CHANGED
@@ -6,7 +6,6 @@
6
6
  line-height: 1.5;
7
7
  --line: #e1e6eb;
8
8
  --muted: #818891;
9
- --blue: #009dff;
10
9
  }
11
10
  * {
12
11
  box-sizing: border-box;
@@ -15,7 +14,7 @@ body {
15
14
  margin: 0;
16
15
  }
17
16
  a {
18
- color: var(--blue);
17
+ color: var(--accent, #009dff);
19
18
  text-decoration: none;
20
19
  }
21
20
  a:hover {
@@ -52,7 +51,7 @@ input:focus-visible,
52
51
  button:focus-visible,
53
52
  a:focus-visible,
54
53
  summary:focus-visible {
55
- outline: 2px solid #76caff;
54
+ outline: 2px solid var(--accent-border, #76caff);
56
55
  outline-offset: 3px;
57
56
  }
58
57
  header {
@@ -123,8 +122,8 @@ kbd {
123
122
  border-bottom: 2px solid transparent;
124
123
  }
125
124
  #tabs a.active {
126
- color: var(--blue);
127
- border-color: var(--blue);
125
+ color: var(--accent, #009dff);
126
+ border-color: var(--accent, #009dff);
128
127
  }
129
128
  .layout {
130
129
  display: grid;
@@ -161,8 +160,8 @@ kbd {
161
160
  overflow-wrap: anywhere;
162
161
  }
163
162
  #documents a.selected {
164
- color: var(--blue);
165
- border-left-color: var(--blue);
163
+ color: var(--accent, #009dff);
164
+ border-left-color: var(--accent, #009dff);
166
165
  }
167
166
  .folder-group summary {
168
167
  list-style: none;
@@ -240,7 +239,7 @@ main {
240
239
  }
241
240
  #breadcrumb a {
242
241
  min-width: 0;
243
- color: #1890ff;
242
+ color: var(--accent, #1890ff);
244
243
  }
245
244
  article {
246
245
  font-size: 16px;
@@ -286,8 +285,8 @@ article strong {
286
285
  transform: rotate(45deg);
287
286
  }
288
287
  .folder-cards a:hover {
289
- background: #f7f9fa;
290
- border-color: #c6d1dc;
288
+ background: var(--accent-soft, #f7f9fa);
289
+ border-color: var(--accent-border, #c6d1dc);
291
290
  text-decoration: none;
292
291
  }
293
292
  .toc[hidden],
@@ -315,7 +314,7 @@ article .document-version {
315
314
  padding: 10px 16px;
316
315
  border: 1px solid var(--line);
317
316
  border-radius: 12px;
318
- background: #f7f9fa;
317
+ background: var(--accent-soft, #f7f9fa);
319
318
  color: #b45309;
320
319
  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
321
320
  font-size: 14px;
@@ -333,7 +332,7 @@ article p {
333
332
  article blockquote {
334
333
  margin: 20px 0;
335
334
  padding: 12px 24px;
336
- border-left: 2px solid #d6dfe6;
335
+ border-left: 2px solid var(--accent-border, #d6dfe6);
337
336
  color: #727b85;
338
337
  }
339
338
  article blockquote p {
@@ -363,8 +362,8 @@ article pre {
363
362
  article code {
364
363
  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
365
364
  font-size: 12px;
366
- background: #f4f7f9;
367
- border: 1px solid #d8e0e7;
365
+ background: var(--accent-soft, #f4f7f9);
366
+ border: 1px solid var(--accent-border, #d8e0e7);
368
367
  border-radius: 3px;
369
368
  padding: 1px 4px;
370
369
  color: #39414a;
@@ -460,8 +459,8 @@ article img {
460
459
  background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' fill='none' stroke='%23727b85' stroke-width='1.3'%3E%3Ccircle cx='6.8' cy='6.8' r='5.2'/%3E%3Cpath d='m10.7 10.7 3.8 3.8'/%3E%3C/svg%3E") center / contain no-repeat;
461
460
  }
462
461
  .section-tools:focus-within {
463
- border-color: #acd3f0;
464
- box-shadow: 0 0 0 2px #acd3f0, 0 4px 10px #62b5ed24;
462
+ border-color: var(--accent-border, #acd3f0);
463
+ box-shadow: 0 0 0 2px var(--accent-border, #acd3f0), 0 4px 10px var(--accent-soft, #62b5ed24);
465
464
  }
466
465
  .section-tools input:focus-visible {
467
466
  outline: none;
@@ -503,7 +502,7 @@ article img {
503
502
  line-height: 1.8;
504
503
  }
505
504
  #toc a:hover {
506
- color: var(--blue);
505
+ color: var(--accent, #009dff);
507
506
  }
508
507
  #pagination {
509
508
  display: flex;
@@ -535,7 +534,7 @@ article img {
535
534
  font-weight: 500;
536
535
  }
537
536
  mark {
538
- background: #fff1ad;
537
+ background: var(--accent-highlight, #fff1ad);
539
538
  color: inherit;
540
539
  border-radius: 2px;
541
540
  }
@@ -588,7 +587,7 @@ dialog::backdrop {
588
587
  border-top: 1px solid var(--line);
589
588
  }
590
589
  .result:hover {
591
- background: #f5f9fc;
590
+ background: var(--accent-soft, #f5f9fc);
592
591
  text-decoration: none;
593
592
  }
594
593
  .result small {
@@ -605,7 +604,7 @@ dialog::backdrop {
605
604
  margin: 4px 0;
606
605
  }
607
606
  .result mark {
608
- background: #dcf0ff;
607
+ background: var(--accent-highlight, #dcf0ff);
609
608
  }
610
609
  @media (max-width: 1200px) {
611
610
  header,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unana_dev/doxen",
3
- "version": "0.2.4",
3
+ "version": "0.2.5",
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
@@ -46,7 +46,7 @@ export async function siteFiles(config, dev = false) {
46
46
  const files = new Map();
47
47
  const initial = new Intl.Segmenter("ko", { granularity: "grapheme" })
48
48
  .segment(config.title.trim().normalize("NFC"))[Symbol.iterator]()
49
- .next().value.segment;
49
+ .next().value.segment.replace(/[a-z]/g, (c) => c.toUpperCase());
50
50
  files.set(
51
51
  "/favicon.svg",
52
52
  Buffer.from(
@@ -64,9 +64,12 @@ export async function siteFiles(config, dev = false) {
64
64
  '<span class="brand-icon">D</span',
65
65
  `<span class="brand-icon">${initial.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)}</span`,
66
66
  );
67
+ const theme = config.color
68
+ ? `;--accent:${config.color};--accent-soft:color-mix(in srgb, ${config.color} 8%, white);--accent-border:color-mix(in srgb, ${config.color} 40%, white);--accent-highlight:color-mix(in srgb, ${config.color} 25%, white)`
69
+ : "";
67
70
  html = html.replace(
68
71
  "</head>",
69
- `<style>:root{--icon-background:${config.icon.background};--icon-color:${config.icon.color};--icon-border:${config.icon.border}}</style></head>`,
72
+ `<style>:root{--icon-background:${config.icon.background};--icon-color:${config.icon.color};--icon-border:${config.icon.border}${theme}}</style></head>`,
70
73
  );
71
74
  html = html.replace(
72
75
  "<title>Doxen</title>",
package/src/config.js CHANGED
@@ -48,10 +48,14 @@ export async function loadConfig(cwd, configPath) {
48
48
  throw new Error("icon은 HEX 색상 또는 background, color, border를 설정하는 객체여야 합니다.");
49
49
  const icon = { background: "#edf8ff", color: "#467792", border: "#bcdff8" };
50
50
  const hexColor = /^#(?:[\da-f]{3}|[\da-f]{6})$/i;
51
- if (typeof config.icon === "string") {
52
- if (!hexColor.test(config.icon))
51
+ if (config.color !== undefined && (typeof config.color !== "string" || !hexColor.test(config.color)))
52
+ throw new Error("color는 #fff 또는 #ffffff 형식의 HEX 색상이어야 합니다.");
53
+ const color = config.color ?? (typeof config.icon === "string" ? config.icon : undefined);
54
+ const iconColor = config.icon ?? config.color;
55
+ if (typeof iconColor === "string") {
56
+ if (!hexColor.test(iconColor))
53
57
  throw new Error("icon은 #fff 또는 #ffffff 형식의 HEX 색상이어야 합니다.");
54
- const hex = config.icon.slice(1);
58
+ const hex = iconColor.slice(1);
55
59
  const fullHex = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
56
60
  const channels = fullHex.match(/../g).map((c) => parseInt(c, 16));
57
61
  const mix = (target, amount) =>
@@ -107,6 +111,7 @@ export async function loadConfig(cwd, configPath) {
107
111
  title: config.title,
108
112
  description: config.description || "",
109
113
  icon,
114
+ color,
110
115
  tabs,
111
116
  root,
112
117
  file,
package/src/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  export interface DocsConfig {
2
2
  title: string;
3
3
  description?: string;
4
+ color?: string;
4
5
  icon?: string | { background?: string; color?: string; border?: string };
5
6
  deploy?: {
6
7
  project: string;