docs/content/content/links.ko.md (3041B)
1 +++
2 title = "내부 링크"
3 description = "소스 파일을 가리키는 링크와, 빌드가 대신 쓰는 URL"
4 weight = 20
5 toc = true
6 +++
7
8 링크를 **파일**로 쓰면 sqzass가 그 페이지의 URL로 바꿔 줍니다.
9
10 ```markdown
11 [설치](@/start/installation.md) 문서를 보세요.
12 ```
13
14 `@/` 뒤의 경로는 `content/` 기준이고, URL이 아니라 마크다운 파일을 가리킵니다.
15 파일을 옮기든 이름을 바꾸든 `slug`를 바꾸든 링크가 따라옵니다.
16
17 ## 깨진 링크는 빌드를 멈춥니다
18
19 아무것도 가리키지 못하는 `@/` 링크는 에러입니다.
20
21 ```
22 docs/content/start/first-site.md: 어디도 가리키지 않는 링크가 있습니다:
23 @/start/setup.md
24 ```
25
26 이게 이 문법의 존재 이유입니다. 아무 데도 안 가는 `/start/setup/` 링크는 누군가
27 프로덕션에서 눌러 보기 전까지 멀쩡한 링크와 구분되지 않습니다. 빌드가 검사할 수
28 있는 참조라면 빌드가 **검사합니다**.
29
30 ## 읽는 사람의 언어를 따라갑니다
31
32 `@/start/installation.md`는 영어 독자에게는 `/start/installation/`으로,
33 한국어 독자에게는 `/ko/start/installation/`으로 풀립니다. 같은 마크다운이 양쪽
34 언어 트리에서, 조건문 하나 없이 동작합니다.
35
36 대상 페이지에 해당 언어 번역이 없으면 링크가 깨지는 대신 기본 언어로 넘어갑니다.
37 [언어](@/content/languages.md)를 참고하세요.
38
39 그 폴백이 있기 때문에 경로는 한 번만 쓰고, 언어 접두사는 절대 붙이지 않습니다.
40 `@/ko/start/installation.md` 같은 건 없습니다.
41
42 ## 트리에서 일어납니다
43
44 재작성은 comrak의 URL 재작성기로, HTML이 만들어지기 **전에** AST 단계에서
45 일어납니다. 흔한 지름길인 "완성된 HTML에 정규식 돌리기"는 속성을 홑따옴표로 쓰거나
46 따옴표를 빼면 조용히 처리에서 빠집니다. 빌드가 아니라 프로덕션에서 발견되는 종류의
47 버그입니다.
48
49 이미지도 같은 *검사기*를 지나지만 문법은 다릅니다. `@/`는 마크다운 페이지 표를
50 뒤지는데 `static/`의 이미지는 그 표에 없으므로 ``는 빌드를
51 멈춥니다. 루트 절대 경로로 씁니다 — ``. 그러면 빌드가 파일이
52 있는지 확인하므로, 이미지 경로의 오타도 링크의 오타와 똑같이 빌드를 멈춥니다.
53
54 ## 생성된 파일도 링크 대상입니다
55
56 `/sitemap.xml`, `/robots.txt`, `/llms.txt`, `/404.html`, `/feed-<언어>.xml`,
57 `/search-<언어>.json`은 검사기 입장에서 페이지와 같습니다. 빌드가 만들어 내므로
58 그것을 가리키는 링크는 해석됩니다.
59
60 예외는 콘텐츠 해시가 붙는 것들입니다. 빌드 뒤에 `/css/main.css`는 존재하지
61 않으므로, 템플릿에서 `asset("css/main.css")`로 가야 합니다.
62
63 ## 나머지는 건드리지 않습니다
64
65 외부 링크, 앵커, `mailto:` — 그대로 둡니다. sqzass가 가져가는 건 `@/` 접두사뿐입니다.