@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 +10 -24
- package/client/style.css +19 -20
- package/package.json +1 -1
- package/src/build.js +5 -2
- package/src/config.js +8 -3
- package/src/index.d.ts +1 -0
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(--
|
|
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(--
|
|
127
|
-
border-color: var(--
|
|
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(--
|
|
165
|
-
border-left-color: var(--
|
|
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(--
|
|
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
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.
|
|
52
|
-
|
|
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 =
|
|
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,
|