docs/content/templates/data.ko.md (4957B)
1 +++
2 title = "템플릿 데이터"
3 description = "템플릿이 읽을 수 있는 모든 것"
4 weight = 20
5 toc = true
6 +++
7
8 모든 페이지에서 `site`와 `page` 두 객체를 쓸 수 있습니다.
9
10 ## site
11
12 | | |
13 |---|---|
14 | `site.title` | `sqzass.toml`에서. |
15 | `site.description` | `sqzass.toml`에서. |
16 | `site.origin` | 스킴과 호스트만. 페이지 URL이 서브경로를 이미 품고 있어서 `{{ site.origin }}{{ page.url }}`이 절대 URL입니다. |
17 | `site.base_path` | 서브경로 아래 사이트일 때의 경로 접두사, 루트면 빈 값. 템플릿이 직접 쓰는 URL에만 필요합니다. |
18 | `site.language` | 지금 렌더 중인 페이지의 언어. |
19 | `site.sections` | **이 언어의** 최상위 섹션들. |
20 | `site.highlight_css` | 생성된 하이라이트 스타일시트 URL. 구문 강조가 꺼져 있으면 없습니다. |
21 | `site.search` | 이 언어의 검색 색인 URL. `[search] enabled = false`면 없습니다. |
22 | `site.feed` | 이 언어의 Atom 피드 URL. 날짜 있는 페이지가 하나도 없으면 없습니다. [피드](@/features/feeds.md)를 참고하세요. |
23
24 `site.sections`에는 현재 언어의 트리만 담깁니다. 내비게이션이 안전한 이유가
25 이것입니다. 번역되지 않은 페이지는 여기 없으므로 그 링크를 그릴 수가 없습니다.
26 각 섹션은 `title`, `description`, `url`, `weight`, `pages`, `subsections`를 갖고,
27 `pages`의 각 항목은 `title`, `description`, `url`, `weight`를 갖습니다.
28
29 ## page
30
31 | | |
32 |---|---|
33 | `page.title` | |
34 | `page.description` | |
35 | `page.url` | `/ko/start/installation/` |
36 | `page.permalink` | 절대 URL — `origin` + `url`. |
37 | `page.content` | 렌더된 HTML. **`\| safe`가 필요합니다.** |
38 | `page.weight`, `page.draft`, `page.language` | front matter 그대로. |
39 | `page.toc` | 저자가 목차를 원했는지. |
40 | `page.toc_entries` | 목차 자체 — `{level, id, title, children}`, 중첩된 형태. |
41 | `page.translations` | 이 페이지가 존재하는 언어만. 비어 있으면 전환 UI를 그리지 않으면 됩니다. |
42 | `page.section` | 이 페이지가 속한 섹션. 최상위 페이지에는 없고, 섹션 인덱스에도 없습니다 — 섹션은 자기 안에 있지 않으니까요. |
43 | `page.prev`, `page.next` | **같은 섹션 안에서의** 이웃 페이지. 같은 이유로 섹션 인덱스에는 없습니다. |
44 | `page.children` | 섹션의 자식 페이지들. 일반 페이지에서는 비어 있습니다. |
45 | `page.is_section` | |
46 | `page.date` | 발행 날짜를 조각으로 — `year`, `month`, `day`, `date`, `iso`. 없으면 없습니다. [피드](@/features/feeds.md)를 참고하세요. |
47 | `page.extra` | 직접 정의한 `[extra]` 테이블. |
48
49 ## page.children은 두 가지입니다
50
51 루트 `_index.md`에서는 최상위 섹션들이 담기고, 그 밖의 섹션에서는 그 섹션의 자식
52 페이지들 뒤에 하위 섹션들이 붙습니다. 둘 다 목록 템플릿이 필요로 하는 것이고, 이름만
53 봐서는 알 수 없습니다.
54
55 ```html
56 {% for child in page.children %}
57 <a href="{{ child.url }}">{{ child.title }}</a>
58 {%- if child.description %}<p>{{ child.description }}</p>{% endif %}
59 {% endfor %}
60 ```
61
62 일반 페이지에서는 빈 목록입니다.
63
64 ## page.toc_entries
65
66 `{level, id, title, children}`이고 상대적 깊이로 중첩됩니다. h2 다음에 h4가 와도
67 중첩되며, 레벨이 연속이라고 가정하지 않습니다. `toc = true`든 아니든 모든 페이지에서
68 수집됩니다. front matter의 `toc`는 저자의 의사이고, 데이터는 어느 쪽이든 있으니
69 템플릿이 판단하면 됩니다.
70
71 그리는 데는 재귀 매크로가 필요합니다.
72
73 ```html
74 {% macro toc_list(entries) %}
75 <ul>
76 {%- for e in entries %}
77 <li><a href="#{{ e.id }}">{{ e.title }}</a>
78 {%- if e.children %}{{ toc_list(e.children) }}{% endif %}
79 </li>
80 {%- endfor %}
81 </ul>
82 {% endmacro %}
83
84 {% if page.toc and page.toc_entries %}{{ toc_list(page.toc_entries) }}{% endif %}
85 ```
86
87 ## asset()
88
89 `asset("css/main.css")`은 그 파일이 실제로 쓰인 해시 붙은 URL을 돌려줍니다.
90
91 ```html
92 <link rel="stylesheet" href="{{ asset("css/main.css") }}">
93 ```
94
95 수집되지 않은 파일을 요청하면 에러입니다. 스타일시트 이름을 바꿨을 때 모든
96 방문자에게 조용히 404를 내는 대신 빌드가 실패합니다.
97
98 ## 슬래시는 이스케이프하지 않습니다
99
100 Jinja2는 다섯 글자를 이스케이프합니다. 일부 포팅 구현은 `/`까지 이스케이프하는데,
101 그러면 모든 페이지의 모든 URL이 `href="https://…"`가 됩니다. sqzass는
102 Jinja2 본래의 동작을 되돌려 두었으므로 URL이 URL로 나옵니다.
103
104 ## 없는 키는 빌드를 멈춥니다
105
106 ```
107 undefined value: page.descriptoin
108 ```
109
110 설명이 있어야 할 자리에 빈 문자열이 들어가는 대신입니다.
111 [템플릿](@/templates/_index.md)을 참고하세요.