docs/content/start/first-site.ko.md (3361B)
1 +++
2 title = "첫 사이트 만들기"
3 description = "빈 디렉터리에서 화면에 뜨는 페이지까지"
4 weight = 20
5 toc = true
6 +++
7
8 ```bash
9 sqzass init mysite
10 sqzass serve -i mysite
11 ```
12
13 이게 전부입니다. `init`이 파일 세 개를 쓰고, `serve`가 그걸
14 <http://127.0.0.1:3000>에 띄웁니다. 네 번째 단계는 없습니다.
15
16 ## 무엇이 만들어졌나
17
18 ```
19 mysite/
20 ├── sqzass.toml
21 ├── content/
22 │ └── _index.md
23 └── templates/
24 └── page.html
25 ```
26
27 세 개뿐입니다. 절반을 지워야 하는 스캐폴드는 출발점이 아니니까요. 요청하지 않은
28 `.gitignore`도, 예제 블로그 글도, sqzass가 자기 것이라고 여기는 디렉터리도
29 만들지 않습니다.
30
31 `init`은 이미 `sqzass.toml`이 있는 디렉터리에서는 실행을 거부합니다. 기존 사이트를
32 반쯤 덮어쓰는 일이 생길 수 없습니다.
33
34 ## sqzass.toml
35
36 키는 둘입니다. 나머지는 전부 기본값이 있고, 적지 않은 키는 그 기본값으로 동작합니다.
37
38 ```toml
39 title = "mysite"
40 base_url = "https://example.com"
41 ```
42
43 ## content/_index.md
44
45 첫 페이지입니다. front matter는 `+++` 펜스 사이의 TOML이고, 반드시 적어야 하는
46 필드는 `title` 하나뿐입니다.
47
48 ```markdown
49 +++
50 title = "mysite"
51 +++
52
53 안녕하세요.
54 ```
55
56 ## templates/page.html
57
58 `page.content`는 이미 HTML이므로 `| safe`가 필요합니다. 템플릿은 기본적으로
59 이스케이프하며, 그 기본값 덕분에 본문에 섞인 `<` 하나가 마크업으로 둔갑하지
60 않습니다.
61
62 ```html
63 <!doctype html>
64 <html lang="{{ page.language }}">
65 <head>
66 <meta charset="utf-8">
67 <title>{{ page.title }}</title>
68 {%- if site.highlight_css %}
69 <link rel="stylesheet" href="{{ site.highlight_css }}">
70 {%- endif %}
71 </head>
72 <body>{{ page.content | safe }}</body>
73 </html>
74 ```
75
76 `site.highlight_css` 줄은 빌드가 구문 테마에서 만들어 주는 스타일시트입니다.
77 빼면 코드 블록에 색이 없이 나옵니다.
78
79 ## 빌드하기
80
81 ```bash
82 sqzass build -i mysite
83 ```
84
85 결과물은 `mysite/public`에 생깁니다. 모든 페이지는 `<경로>.html`이 아니라
86 `<경로>/index.html`로 쓰이므로 URL이 `/about.html`이 아니라 `/about/`이 됩니다.
87 rewrite 규칙이 없는 호스트에서 왜 이게 중요한지는
88 [콘텐츠 작성](@/content/_index.md)에 적어 두었습니다. sitemap과 `robots.txt`도
89 같이 나옵니다.
90
91 ## 작업하기
92
93 `sqzass serve`는 파일이 바뀌면 다시 빌드합니다. 도는 동안 `public/`에는 아무것도
94 쓰지 않으므로, 빌드 중인 사이트가 반쯤 쓰인 파일을 내보내는 일이 없습니다. 페이지는
95 스스로 새로고침하고, CSS만 바뀐 변경은 스타일시트만 갈아 끼워 스크롤 위치를
96 유지합니다.
97
98 > [!NOTE]
99 > 개발 서버는 개발용 도구입니다. 캐싱도, 압축도, 접근 제어도 하지 않습니다.
100 > 프로덕션에서는 빌드된 디렉터리를 제대로 된 서버로 서빙하세요.
101
102 ## 다음에 더할 것
103
104 페이지를 하나 더 만드는 건 파일을 하나 더 만드는 일입니다. `content/about.md`는
105 `/about/`이 되고, `content/guide/_index.md`는 그 옆의 파일들을 묶는 섹션을
106 시작합니다. 페이지가 가질 수 있는 필드는
107 [front matter](@/content/front-matter.md)에 정리해 두었습니다.