docs/content/start/configuration.ko.md (4584B)
1 +++
2 title = "설정"
3 description = "sqzass.toml의 모든 키와, 오타를 냈을 때 벌어지는 일"
4 weight = 30
5 toc = true
6 +++
7
8 `sqzass.toml`은 사이트 루트에 둡니다. 반드시 있어야 하는 키는 둘이고, 나머지는
9 전부 기본값이 있어 적지 않으면 그 기본값으로 동작합니다.
10
11 ```toml
12 title = "내 사이트"
13 base_url = "https://example.com"
14 ```
15
16 ## 오타는 에러입니다
17
18 ```
19 error: [SQZASS_E_CONFIG] sqzass.toml 파싱 실패: TOML parse error at line 8, column 1
20 |
21 8 | theme_ligth = "InspiredGitHub"
22 | ^^^^^^^^^^^
23 unknown field `theme_ligth`, expected one of `enabled`, `theme_light`, `theme_dark`
24 ```
25
26 sqzass가 읽지 않는 키는 아무 일도 하지 않는 키이고, 조용히 아무 일도 하지 않는
27 설정은 깨진 링크와 같은 종류의 실패입니다. 무언가를 요청했고, 도구는 알겠다고 했고,
28 아무 일도 일어나지 않았습니다. 테마가 왜 안 바뀌는지 찾느라 오후를 쓰게 됩니다.
29
30 front matter도 마찬가지이고, 에러가 가리키는 줄 번호는 front matter 블록 기준이
31 아니라 **파일 기준**입니다.
32
33 ## 사이트
34
35 | 키 | 기본값 | |
36 |---|---|---|
37 | `title` | — | **필수.** |
38 | `base_url` | — | **필수.** canonical URL, sitemap, `robots.txt`가 씁니다. |
39 | `description` | `""` | |
40 | `default_language` | `"en"` | 이 언어가 루트를 쓰고, 나머지는 URL 접두사를 갖습니다. |
41
42 ## `[languages.<코드>]`
43
44 ```toml
45 [languages.en]
46 name = "English"
47 weight = 1
48
49 [languages.ko]
50 name = "한국어"
51 weight = 2
52 ```
53
54 `name`은 언어 전환 UI에 보이는 이름이고, `weight`는 순서입니다. 언어를 아예
55 선언하지 않아도 됩니다. 그러면 `default_language` 하나로 도는 단일 언어 사이트가
56 됩니다. [언어](@/content/languages.md)를 참고하세요.
57
58 ## `[build]`
59
60 | 키 | 기본값 | |
61 |---|---|---|
62 | `output_dir` | `"public"` | 사이트 루트 기준. |
63 | `drafts` | `false` | 명령줄의 `--drafts`가 이걸 켭니다. |
64
65 드래프트는 CSS로 감추는 게 아니라 빌드에서 통째로 빠집니다.
66 [콘텐츠 작성](@/content/_index.md)을 참고하세요.
67
68 ## `[markdown]`
69
70 | 키 | 기본값 | |
71 |---|---|---|
72 | `footnotes` | `true` | |
73 | `tables` | `true` | |
74 | `tasklist` | `true` | |
75 | `strikethrough` | `true` | |
76 | `autolink` | `true` | |
77 | `alerts` | `true` | GitHub의 `> [!NOTE]` 콜아웃. |
78 | `cjk_friendly_emphasis` | `true` | **한국어라면 켜 두세요.** |
79 | `heading_anchors` | `"right"` | `none`, `left`, `right`. |
80
81 `cjk_friendly_emphasis`가 `**강조**한다`를 강조로 파싱되게 하는 키입니다.
82 CommonMark의 flanking 규칙은 단어 사이에 공백을 두는 언어를 전제로 하고, 이게
83 없으면 굵게 표시한 부분 바로 뒤에 조사가 붙은 형태는 강조가 아예 아닙니다. 끄면
84 한국어 본문이 "내 마크다운이 틀렸나" 싶은 모양으로 깨집니다.
85 [마크다운](@/content/markdown.md)을 참고하세요.
86
87 ## `[highlight]`
88
89 | 키 | 기본값 | |
90 |---|---|---|
91 | `enabled` | `true` | |
92 | `theme_light` | `"InspiredGitHub"` | |
93 | `theme_dark` | `"base16-ocean.dark"` | |
94
95 없는 테마 이름을 쓰면 에러이고, 메시지에 쓸 수 있는 이름들이 같이 나옵니다.
96 [구문 강조](@/features/highlighting.md)를 참고하세요.
97
98 ## `[assets]`
99
100 | 키 | 기본값 | |
101 |---|---|---|
102 | `source_dir` | `"static"` | |
103 | `fingerprint` | `true` | CSS와 JS의 파일명에 콘텐츠 해시를 붙입니다. |
104
105 [정적 에셋](@/templates/assets.md)을 참고하세요.
106
107 ## `[nav]`
108
109 | 키 | 기본값 | |
110 |---|---|---|
111 | `sort_by` | `"weight"` | `weight`, `title`, `date`. 섹션이 각자 덮어쓸 수 있습니다. |
112
113 섹션마다 덮어쓰는 방법과 `date`만 내림차순인 이유는
114 [콘텐츠 작성](@/content/_index.md)에 적어 두었습니다.
115
116 ## `[search]`
117
118 | 키 | 기본값 | |
119 |---|---|---|
120 | `enabled` | `true` | 언어별 `search-<lang>.json`을 만듭니다. |
121
122 색인은 모든 페이지의 본문을 담아 콘텐츠와 함께 커집니다 — 검색 UI가 없는
123 사이트가 그 값을 치를 이유가 없습니다. 끄면 색인이 만들어지지 않고, 링크가
124 가리킬 색인 URL도 존재하지 않게 됩니다. [검색](@/features/search.md)을
125 참고하세요.
126
127 ## 명령줄에서 덮어쓰기
128
129 `--base-url`과 `--drafts`는 파일보다 우선합니다. 설정 하나로 프리뷰 배포와
130 프로덕션을 함께 다룰 수 있는 이유입니다.
131
132 ```bash
133 sqzass build -i mysite --base-url https://preview.example.com --drafts
134 ```