라우팅
도큐사우루스의 라우팅 시스템은 단일 페이지 애플리케이션 규칙을 따릅니다. 하나의 경로, 하나의 컴포넌트. 세 가지 콘텐츠 플러그인(문서, 블로그, 페이지) 내에서 라우팅에 대해 설명한 다음 기본 라우팅 시스템에 대해 설명합니다.
Routing in content plugins
Every content plugin provides a routeBasePath
option. 해당 옵션에서는 플러그인이 경로를 추가하는 위치를 정의합니다. By default, the docs plugin puts its routes under /docs
; the blog plugin, /blog
; and the pages plugin, /
. 다음과 같이 경로 구조에 대해 생각할 수 있습니다.
모든 경로는 일치하는 항목이 발견될 때까지 중첩된 경로 설정을 탐색합니다. For example, when given a route /docs/configuration
, Docusaurus first enters the /docs
branch, and then searches among the subroutes created by the docs plugin.
Changing routeBasePath
can effectively alter your site's route structure. For example, in Docs-only mode, we mentioned that configuring routeBasePath: '/'
for docs means that all routes that the docs plugin create would not have the /docs
prefix, yet it doesn't prevent you from having more subroutes like /blog
created by other plugins.
다음은 세 가지 플러그인이 자체 "서브라우트 박스"를 구성하는 방법을 살펴보겠습니다.
Pages routing
페이지 라우팅은 간단합니다. 별도의 사용자 정의 없이 파일 경로가 URL에 직접 연결됩니다. See the pages docs for more information.
The component used for Markdown pages is @theme/MDXPage
. 리액트 페이지는 라우트 컴포넌트처럼 직접 사용됩니다.
Blog routing
블로그는 다음과 같은 경로를 만듭니다.
- Posts list pages:
/
,/page/2
,/page/3
...- The route is customizable through the
pageBasePath
option. - The component is
@theme/BlogListPage
.
- The route is customizable through the
- Post pages:
/2021/11/21/algolia-docsearch-migration
,/2021/05/12/announcing-docusaurus-two-beta
...- 각 마크다운 게시물에서 만듭니다.
- The routes are fully customizable through the
slug
front matter. - The component is
@theme/BlogPostPage
.
- Tags list page:
/tags
- The route is customizable through the
tagsBasePath
option. - The component is
@theme/BlogTagsListPage
.
- The route is customizable through the
- Tag pages:
/tags/adoption
,/tags/beta
...- 각 게시물 프런트매터에 정의된 태그를 통해 만듭니다.
- The routes always have base defined in
tagsBasePath
, but the subroutes are customizable through the tag'spermalink
field. - The component is
@theme/BlogTagsPostsPage
.
- Archive page:
/archive
- The route is customizable through the
archiveBasePath
option. - The component is
@theme/BlogArchivePage
.
- The route is customizable through the
Docs routing
The docs is the only plugin that creates nested routes. At the top, it registers version paths: /
, /next
, /2.0.0-beta.13
... which provide the version context, including the layout and sidebar. 이렇게 하면 개별 문서 간 전환 시 사이드바 상태가 유지되고 같은 문서에 머무르면서 메뉴바에서 버전 드롭다운 목록을 선택해 다른 버전으로 전환할 수 있습니다. The component used is @theme/DocPage
.
The individual docs are rendered in the remaining space after the navbar, footer, sidebar, etc. have all been provided by the DocPage
component. 예를 들어 이 페이지, /ko/docs/advanced/routing
, 는 ./versioned_docs/version-3.2.1/advanced/routing.md
에 있는 파일에서 만들어졌습니다. The component used is @theme/DocItem
.
The doc's slug
front matter customizes the last part of the route, but the base route is always defined by the plugin's routeBasePath
and the version's path
.
File paths and URL paths
문서 전체에서 우리는 항상 파일 경로 또는 URL 경로에 대해 모호하지 않게 표현 하려고 노력하고 있습니다. Content plugins usually map file paths directly to URL paths, for example, ./docs/advanced/routing.md
will become /docs/advanced/routing
. However, with slug
, you can make URLs totally decoupled from the file structure.
When writing links in Markdown, you could either mean a file path, or a URL path, which Docusaurus would use several heuristics to determine.
- If the path has a
@site
prefix, it is always an asset file path. - If the path has an
http(s)://
prefix, it is always a URL path. - 경로에 확장자가 없다면 URL 경로입니다. For example, a link
[page](../plugins)
on a page with URL/docs/advanced/routing
will link to/docs/plugins
. 도큐사우루스는 사이트 구축 시(전체 경로 구조를 알고 있을 때) 끊어진 링크만 감지하고 파일의 존재 여부에 대해서는 가정하지 않습니다. It is exactly equivalent to writing<a href="../plugins">page</a>
in a JSX file. - If the path has an
.md(x)
extension, Docusaurus would try to resolve that Markdown file to a URL, and replace the file path with a URL path. - If the path has any other extension, Docusaurus would treat it as an asset and bundle it.
다음 디렉터리 구조는 파일 → URL mapping 을 시각화하는데 도움을 줍니다. 어떤 페이지도 사용자 정의 슬러그가 없다고 가정합니다.
A sample site structure
.
├── blog # blog plugin has routeBasePath: '/blog'
│ ├── 2019-05-28-first-blog-post.md # -> /blog/2019/05/28/first-blog-post
│ ├── 2019-05-29-long-blog-post.md # -> /blog/2019/05/29/long-blog-post
│ ├── 2021-08-01-mdx-blog-post.mdx # -> /blog/2021/08/01/mdx-blog-post
│ └── 2021-08-26-welcome
│ ├── docusaurus-plushie-banner.jpeg
│ └── index.md # -> /blog/2021/08/26/welcome
├── docs # docs plugin has routeBasePath: '/docs'; current version has base path '/'
│ ├── intro.md # -> /docs/intro
│ ├── tutorial-basics
│ │ ├── _category_.json
│ │ ├── congratulations.md # -> /docs/tutorial-basics/congratulations
│ │ └── markdown-features.mdx # -> /docs/tutorial-basics/markdown-features
│ └── tutorial-extras
│ ├── _category_.json
│ ├── manage-docs-versions.md # -> /docs/tutorial-extras/manage-docs-versions
│ └── translate-your-site.md # -> /docs/tutorial-extras/translate-your-site
├── src
│ └── pages # pages plugin has routeBasePath: '/'
│ ├── index.module.css
│ ├── index.tsx # -> /
│ └── markdown-page.md # -> /markdown-page
└── versioned_docs
└── version-1.0.0 # version has base path '/1.0.0'
├── intro.md # -> /docs/1.0.0/intro
├── tutorial-basics
│ ├── _category_.json
│ ├── congratulations.md # -> /docs/1.0.0/tutorial-basics/congratulations
│ └── markdown-features.mdx # -> /docs/1.0.0/tutorial-basics/markdown-features
└── tutorial-extras
├── _category_.json
├── manage-docs-versions.md # -> /docs/1.0.0/tutorial-extras/manage-docs-versions
└── translate-your-site.md # -> /docs/1.0.0/tutorial-extras/translate-your-site