sqzass
English

설정

sqzass.toml의 모든 키와, 오타를 냈을 때 벌어지는 일

sqzass.toml은 사이트 루트에 둡니다. 반드시 있어야 하는 키는 둘이고, 나머지는 전부 기본값이 있어 적지 않으면 그 기본값으로 동작합니다.

title    = "내 사이트"
base_url = "https://example.com"

오타는 에러입니다

error: [SQZASS_E_CONFIG] sqzass.toml 파싱 실패: TOML parse error at line 8, column 1
  |
8 | theme_ligth = "InspiredGitHub"
  | ^^^^^^^^^^^
unknown field `theme_ligth`, expected one of `enabled`, `theme_light`, `theme_dark`

sqzass가 읽지 않는 키는 아무 일도 하지 않는 키이고, 조용히 아무 일도 하지 않는 설정은 깨진 링크와 같은 종류의 실패입니다. 무언가를 요청했고, 도구는 알겠다고 했고, 아무 일도 일어나지 않았습니다. 테마가 왜 안 바뀌는지 찾느라 오후를 쓰게 됩니다.

front matter도 마찬가지이고, 에러가 가리키는 줄 번호는 front matter 블록 기준이 아니라 파일 기준입니다.

사이트

키 기본값
title — 필수.
base_url — 필수. canonical URL, sitemap, robots.txt가 씁니다.
description ""
default_language "en" 이 언어가 루트를 쓰고, 나머지는 URL 접두사를 갖습니다.

[languages.<코드>]

[languages.en]
name   = "English"
weight = 1

[languages.ko]
name   = "한국어"
weight = 2

name은 언어 전환 UI에 보이는 이름이고, weight는 순서입니다. 언어를 아예 선언하지 않아도 됩니다. 그러면 default_language 하나로 도는 단일 언어 사이트가 됩니다. 언어를 참고하세요.

[build]

키 기본값
output_dir "public" 사이트 루트 기준.
drafts false 명령줄의 --drafts가 이걸 켭니다.

드래프트는 CSS로 감추는 게 아니라 빌드에서 통째로 빠집니다. 콘텐츠 작성을 참고하세요.

[markdown]

키 기본값
footnotes true
tables true
tasklist true
strikethrough true
autolink true
alerts true GitHub의 > [!NOTE] 콜아웃.
cjk_friendly_emphasis true 한국어라면 켜 두세요.
heading_anchors "right" none, left, right.

cjk_friendly_emphasis가 **강조**한다를 강조로 파싱되게 하는 키입니다. CommonMark의 flanking 규칙은 단어 사이에 공백을 두는 언어를 전제로 하고, 이게 없으면 굵게 표시한 부분 바로 뒤에 조사가 붙은 형태는 강조가 아예 아닙니다. 끄면 한국어 본문이 "내 마크다운이 틀렸나" 싶은 모양으로 깨집니다. 마크다운을 참고하세요.

[highlight]

키 기본값
enabled true
theme_light "InspiredGitHub"
theme_dark "base16-ocean.dark"

없는 테마 이름을 쓰면 에러이고, 메시지에 쓸 수 있는 이름들이 같이 나옵니다. 구문 강조를 참고하세요.

[assets]

키 기본값
source_dir "static"
fingerprint true CSS와 JS의 파일명에 콘텐츠 해시를 붙입니다.

정적 에셋을 참고하세요.

키 기본값
sort_by "weight" weight, title, date. 섹션이 각자 덮어쓸 수 있습니다.

섹션마다 덮어쓰는 방법과 date만 내림차순인 이유는 콘텐츠 작성에 적어 두었습니다.

키 기본값
enabled true 언어별 search-<lang>.json을 만듭니다.

색인은 모든 페이지의 본문을 담아 콘텐츠와 함께 커집니다 — 검색 UI가 없는 사이트가 그 값을 치를 이유가 없습니다. 끄면 색인이 만들어지지 않고, 링크가 가리킬 색인 URL도 존재하지 않게 됩니다. 검색을 참고하세요.

명령줄에서 덮어쓰기

--base-url과 --drafts는 파일보다 우선합니다. 설정 하나로 프리뷰 배포와 프로덕션을 함께 다룰 수 있는 이유입니다.

sqzass build -i mysite --base-url https://preview.example.com --drafts