마크다운 링크
다른 페이지로 연결되는 링크를 추가하는 방법은 두 가지입니다: URL 경로를 사용하는 방법과 파일 경로를 사용하는 방법입니다.
- [다른 문서의 URL 경로](./installation)
- [다른 문서의 파일 경로](./installation.mdx)
URL 경로는 도큐사우루스가 처리하지 않으며, \<a href="./installation">로 직접 렌더링된다고 볼 수 있습니다. 즉, 파일 시스템상의 위치가 아니라 페이지의 URL 위치를 기준으로 해석됩니다.
같은 플러그인에 포함된 다른 Markdown 파일을 참조하려면, 연결하려는 문서의 상대 경로를 사용할 수 있습니다. 도큐사우루스의 Markdown 로더는 파일 경로를 대상 파일의 URL 경로로 변환합니다 (따라서 .md 확장자는 제거됩니다).
For example, if you are in docs/folder/doc1.md and you want to reference docs/folder/doc2.md, docs/folder/subfolder/doc3.md and docs/otherFolder/doc4.md:
[문서](doc2.mdx)를 참조하고 있습니다.
[하위 폴더에 있는 다른 문서](subfolder/doc3.mdx)를 참조합니다.
[상대 경로의 문서](../otherFolder/doc4.mdx)를 참조하는 것도 가능합니다.
상대 파일 경로는 현재 파일의 디렉터리에 따라 정해집니다. 반면 절대 파일 경로는 콘텐츠 루트를 기준으로 해석되며, 일반적으로 docs/, blog/ 또는 i18n/zh-Hans/plugin-content-docs/current 같은 현지화된 경로가 기준이 됩니다.
현재 파일이 website/docs/category/source.mdx라고 가정할 때, 다음은 파일 경로 링크와 해당 링크가 해석되는 방식의 예입니다:
[link](./target.mdx)는 현재 파일의 디렉터리인website/docs/category를 기준으로 해석됩니다.[link](../target.mdx)는 상위 디렉터리인website/docs를 기준으로 해석됩니다.[link](/target.mdx)는 문서 콘텐츠 루트인website/docs를 기준으로 해석되며, 현지화된 문서가 우선적으로 사용됩니다.[link](target.mdx)는 현재 디렉터리인website/docs/category, 문서 콘텐츠 루트, 사이트 루트 순으로 해석됩니다.
절대 파일 경로도 사이트 디렉터리를 기준으로 정할 수 있습니다. 하지만 /docs/, /blog/ 또는 @site/로 시작하는 링크는 새 문서 버전을 만들거나 현지화할 때 직접 업데이트해야 하므로 이식성이 없다는 점에 주의하세요:
[link](/docs/target.mdx)는 사이트 루트인website를 기준으로 해석됩니다 (⚠️ 이식성이 낮음).[link](@site/docs/target.mdx)는 사이트 루트인website를 기준으로 하는 상대 경로입니다 (⚠️ 이식성이 낮음).
상대 URL 링크 대신 상대 파일 경로 (.md 확장자 포함)를 사용하면 다음과 같은 이점이 있습니다:
- 링크는 깃허브 인터페이스나 다른 마크다운 편집기에서 계속 작동합니다.
- 모든 링크를 업데이트하지 않고 파일 슬러그만 원하는 형태로 변경할 수 있습니다.
- 폴더 간 파일 이동을 편집기에서 추적할 수 있으며 일부 편집기는 파일 링크를 자동으로 업데이트할 수 있습니다.
- 버전이 지정된 문서는 정확히 같은 버전의 다른 문서로 연결됩니다
trailingSlash설정을 변경하면 상대 URL 링크가 깨질 가능성이 매우 높습니다
마크다운 파일 참조는 소스 및 대상 파일이 같은 플러그인 인스턴스에서 처리될 때만 작동합니다. 이는 마크다운 프로세싱 아키텍처의 기술적 제약이며 향후 수정될 수 있습니다. 플러그인 간 파일을 연결하는 경우(예: 블로그 게시물에서 문서 페이지로 연결)에는 URL 링크를 사용해야 합니다.