docs/content/start/configuration.md (4003B)
1 +++
2 title = "Configuration"
3 description = "Every key in sqzass.toml, and what happens when you misspell one"
4 weight = 30
5 toc = true
6 +++
7
8 `sqzass.toml` sits at the site root. Two keys are required; everything else has
9 a default and behaves as if you had written the default.
10
11 ```toml
12 title = "My site"
13 base_url = "https://example.com"
14 ```
15
16 ## A typo is an error
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 A key sqzass does not read is a key that does nothing, and a setting that
27 silently does nothing is the same failure as a broken link: you asked for
28 something, the tool agreed, and nothing happened. You would spend the afternoon
29 wondering why your theme did not change.
30
31 The same applies in front matter, and the line number points into your file
32 rather than into the front matter block.
33
34 ## Site
35
36 | Key | Default | |
37 |---|---|---|
38 | `title` | — | **Required.** |
39 | `base_url` | — | **Required.** Used for canonical URLs, the sitemap and `robots.txt`. |
40 | `description` | `""` | |
41 | `default_language` | `"en"` | This language lives at the root; others get a URL prefix. |
42
43 ## `[languages.<code>]`
44
45 ```toml
46 [languages.en]
47 name = "English"
48 weight = 1
49
50 [languages.ko]
51 name = "한국어"
52 weight = 2
53 ```
54
55 `name` is what a language switcher shows. `weight` orders them. Declaring no
56 languages at all is fine — the site is then single-language under
57 `default_language`. See [Languages](@/content/languages.md).
58
59 ## `[build]`
60
61 | Key | Default | |
62 |---|---|---|
63 | `output_dir` | `"public"` | Relative to the site root. |
64 | `drafts` | `false` | `--drafts` sets this from the command line. |
65
66 A draft is excluded from the build entirely, not hidden by CSS. See
67 [Writing content](@/content/_index.md).
68
69 ## `[markdown]`
70
71 | Key | Default | |
72 |---|---|---|
73 | `footnotes` | `true` | |
74 | `tables` | `true` | |
75 | `tasklist` | `true` | |
76 | `strikethrough` | `true` | |
77 | `autolink` | `true` | |
78 | `alerts` | `true` | GitHub's `> [!NOTE]` callouts. |
79 | `cjk_friendly_emphasis` | `true` | **Leave this on for Korean.** |
80 | `heading_anchors` | `"right"` | `none`, `left` or `right`. |
81
82 `cjk_friendly_emphasis` is what makes `**강조**한다` parse as emphasis.
83 CommonMark's flanking rules assume spaces around words, and without this a bold
84 run followed immediately by a Korean particle is not emphasis at all. Turning it
85 off breaks Korean text in a way that reads like your markdown is wrong. See
86 [Markdown](@/content/markdown.md).
87
88 ## `[highlight]`
89
90 | Key | Default | |
91 |---|---|---|
92 | `enabled` | `true` | |
93 | `theme_light` | `"InspiredGitHub"` | |
94 | `theme_dark` | `"base16-ocean.dark"` | |
95
96 A theme name that does not exist is an error, and the message lists the ones
97 that do. See [Syntax highlighting](@/features/highlighting.md).
98
99 ## `[assets]`
100
101 | Key | Default | |
102 |---|---|---|
103 | `source_dir` | `"static"` | |
104 | `fingerprint` | `true` | Content hash in the filename, for CSS and JS. |
105
106 See [Static assets](@/templates/assets.md).
107
108 ## `[nav]`
109
110 | Key | Default | |
111 |---|---|---|
112 | `sort_by` | `"weight"` | `weight`, `title` or `date`. A section can override it. |
113
114 How a section overrides it, and why `date` alone sorts newest first, are in
115 [Writing content](@/content/_index.md).
116
117 ## `[search]`
118
119 | Key | Default | |
120 |---|---|---|
121 | `enabled` | `true` | Emit `search-<lang>.json`, one per language. |
122
123 The index carries the body text of every page, so it grows with your content —
124 a site with no search UI has no reason to pay for it. Disabled, no index is
125 written and no index URL exists for links to point at. See
126 [Search](@/features/search.md).
127
128 ## Overriding from the command line
129
130 `--base-url` and `--drafts` win over the file, which is what makes one
131 configuration serve both a preview deployment and production.
132
133 ```bash
134 sqzass build -i mysite --base-url https://preview.example.com --drafts
135 ```