마크다운 링크
URL 경로와 파일 경로를 통해 다른 페이지에 대한 링크를 추가하는 두 가지 방법이 있습니다.
- [다른 문서의 URL 경로](./installation)
- [다른 문서의 파일 경로](./installation.mdx)
URL 경로는 도큐사우루스에 의해 처리되지 않으며 <a href="./installation">처럼 직접 렌더링되는 것을 확인할 수 있습니다. 즉, 파일 시스템 위치가 아닌 페이지의 URL 위치에 따라 처리됩니다.
같은 플러그인에 포함된 다른 마크다운 파일을 참조하려면 링크하려는 문서의 상대 경로를 사용할 수 있습니다. 도큐사우루스의 마크다운 로더는 파일 경로를 대상 파일의 URL 경로로 변환합니다(따라서 .md 확장자를 제거합니다).
예를 들어 docs/folder/doc1.md 파일에서 docs/folder/doc2.md, docs/folder/subfolder/doc3.md, docs/otherFolder/doc4.md 파일을 참조하고자 한다면 아래와 같이 설정할 수 있습니다.
[document](doc2.mdx)를 참조합니다.
다른 [하위 폴더에 있는 문서](subfolder/doc3.mdx)를 참조합니다.
[상대 경로에 있는 문서](../otherFolder/doc4.mdx)도 참조할 수 있습니다.
상대 파일 경로는 현재 파일의 디렉터리에 따라 정해집니다. 반면에 절대 파일 경로는 콘텐츠 루트, 일반적으로 docs/, blog/ 또는 i18n/zh-Hans/plugin-content-docs/current처럼 현지화된 경로를 기준으로 정해집니다.
절대 파일 경로도 사이트 디렉터리를 기준으로 정할 수 있습니다. 하지만 /docs/ 또는 /blog/로 시작하는 링크는 새로운 문서 버전을 만들거나 현지화하는 경우 수동으로 업데이트해야 하기 때문에 적합하지 않습니다.
콘텐츠 루트(`/docs/`)를 기준으로 [links](/otherFolder/doc4.mdx)를 작성할 수 있습니다.
사이트 디렉토리를 기준으로 [links](/docs/otherFolder/doc4.mdx)를 작성할 수도 있지만 권장하지 않습니다.
상대 URL 링크 대신 상대 파일 경로(.md 확장자를 가진)를 사용하면 다음과 같은 이점이 있습니다.
- 링크는 깃허브 인터페이스나 다른 마크다운 편집기에서 계속 작동합니다.
- 모든 링크를 업데이트하지 않고 파일 슬러그만 원하는 형태로 변경할 수 있습니다.
- 폴더 간 파일 이동을 편집기에서 추적할 수 있으며 일부 편집기는 파일 링크를 자동으로 업데이트할 수 있습니다.
- 버전이 지정된 문서는 정확하게 같은 버전의 다른 문서에 링크됩니다.
- 상대 URL 링크는
trailingSlash설정 변경 시 깨질 수 있습니다.
마크다운 파일 참조는 소스 및 대상 파일이 같은 플러그인 인스턴스에서 처리될 때만 작동합니다. 이는 마크다운 프로세싱 아키텍처의 기술적 제약이며 향후 수정될 수 있습니다. 플러그인 간 파일을 연결하는 경우(예: 블로그 게시물에서 문서 페이지로 연결)에는 URL 링크를 사용해야 합니다.