내부 링크
소스 파일을 가리키는 링크와, 빌드가 대신 쓰는 URL
링크를 파일로 쓰면 sqzass가 그 페이지의 URL로 바꿔 줍니다.
@/ 뒤의 경로는 content/ 기준이고, URL이 아니라 마크다운 파일을 가리킵니다.
파일을 옮기든 이름을 바꾸든 slug를 바꾸든 링크가 따라옵니다.
깨진 링크는 빌드를 멈춥니다
아무것도 가리키지 못하는 @/ 링크는 에러입니다.
docs/content/start/first-site.md: 어디도 가리키지 않는 링크가 있습니다:
@/start/setup.md
이게 이 문법의 존재 이유입니다. 아무 데도 안 가는 /start/setup/ 링크는 누군가
프로덕션에서 눌러 보기 전까지 멀쩡한 링크와 구분되지 않습니다. 빌드가 검사할 수
있는 참조라면 빌드가 검사합니다.
읽는 사람의 언어를 따라갑니다
@/start/installation.md는 영어 독자에게는 /start/installation/으로,
한국어 독자에게는 /ko/start/installation/으로 풀립니다. 같은 마크다운이 양쪽
언어 트리에서, 조건문 하나 없이 동작합니다.
대상 페이지에 해당 언어 번역이 없으면 링크가 깨지는 대신 기본 언어로 넘어갑니다. 언어를 참고하세요.
그 폴백이 있기 때문에 경로는 한 번만 쓰고, 언어 접두사는 절대 붙이지 않습니다.
@/ko/start/installation.md 같은 건 없습니다.
트리에서 일어납니다
재작성은 comrak의 URL 재작성기로, HTML이 만들어지기 전에 AST 단계에서 일어납니다. 흔한 지름길인 "완성된 HTML에 정규식 돌리기"는 속성을 홑따옴표로 쓰거나 따옴표를 빼면 조용히 처리에서 빠집니다. 빌드가 아니라 프로덕션에서 발견되는 종류의 버그입니다.
이미지도 같은 검사기를 지나지만 문법은 다릅니다. @/는 마크다운 페이지 표를
뒤지는데 static/의 이미지는 그 표에 없으므로 는 빌드를
멈춥니다. 루트 절대 경로로 씁니다 — . 그러면 빌드가 파일이
있는지 확인하므로, 이미지 경로의 오타도 링크의 오타와 똑같이 빌드를 멈춥니다.
생성된 파일도 링크 대상입니다
/sitemap.xml, /robots.txt, /llms.txt, /404.html, /feed-<언어>.xml,
/search-<언어>.json은 검사기 입장에서 페이지와 같습니다. 빌드가 만들어 내므로
그것을 가리키는 링크는 해석됩니다.
예외는 콘텐츠 해시가 붙는 것들입니다. 빌드 뒤에 /css/main.css는 존재하지
않으므로, 템플릿에서 asset("css/main.css")로 가야 합니다.
나머지는 건드리지 않습니다
외부 링크, 앵커, mailto: — 그대로 둡니다. sqzass가 가져가는 건 @/ 접두사뿐입니다.