You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
import {useActiveDocContext} from '@docusaurus/plugin-content-docs/client';
11
+
import {useLocation} from '@docusaurus/router';
12
+
import BrowserOnly from '@docusaurus/BrowserOnly';
13
+
```
14
+
15
+
Docusaurus uses a **single-page application (SPA)** routing system — meaning every route corresponds to **one component**.
16
+
17
+
In this guide, we’ll explore how Docusaurus manages routing for **Docs**, **Blog**, and **Pages**, and then dive deeper into how the routing system itself works behind the scenes.
18
+
19
+
---
20
+
21
+
## Routing in Content Plugins {#routing-in-content-plugins}
22
+
23
+
Each content plugin defines a `routeBasePath`, which tells Docusaurus **where to mount routes**.
24
+
25
+
-**Docs plugin:**`/docs` by default
26
+
-**Blog plugin:**`/blog`
27
+
-**Pages plugin:**`/`
28
+
29
+
Here’s how these routes connect in the URL hierarchy:
30
+
31
+
```mermaid
32
+
graph LR;
33
+
A(["https://codeharborhub.github.io/"])
34
+
B(["/base-url/"])
35
+
C(["/docs/"])
36
+
D(["/blog/"])
37
+
E(["/"])
38
+
F["Docs Routes"]
39
+
G["Blog Routes"]
40
+
H["Page Routes"]
41
+
A---B;
42
+
B---C;
43
+
B---D;
44
+
B---E;
45
+
C---F;
46
+
D---G;
47
+
E---H;
48
+
```
49
+
50
+
When a user visits `/docs/configuration`, Docusaurus finds the `/docs` branch, and then loads the corresponding document route.
51
+
52
+
You can fully customize your route structure. For instance, setting `routeBasePath: '/'` in **Docs-only mode** removes the `/docs` prefix while keeping all other plugins intact.
53
+
54
+
---
55
+
56
+
## Pages Routing {#pages-routing}
57
+
58
+
**Pages** are the simplest form of routes — file paths directly map to URLs.
59
+
For example:
60
+
61
+
```
62
+
src/pages/about.mdx → /about
63
+
src/pages/index.js → /
64
+
```
65
+
66
+
- Markdown pages render using `@theme/MDXPage`.
67
+
- React components render directly as route components.
68
+
69
+
See [Creating Pages](../guides/creating-pages.mdx#routing) for more details.
70
+
71
+
---
72
+
73
+
## Blog Routing {#blog-routing}
74
+
75
+
The blog plugin auto-generates several types of routes:
76
+
77
+
| Route Type | Example URL | Customizable Option | Component |
This page, <BrowserOnly>{()=> <URLPath /> }</BrowserOnly>, is generated from <BrowserOnly>{()=> <FilePath />}</BrowserOnly>. The doc content is displayed inside `@theme/DocPage`, which manages layout, sidebar, and navigation.
112
+
113
+
---
114
+
115
+
## File Paths vs URL Paths {#file-paths-and-url-paths}
116
+
117
+
In Docusaurus, **file paths map to URL paths**, unless overridden using the `slug` front matter.
- Other extensions → Treated as [assets](../guides/markdown-features/markdown-features-assets.mdx)
133
+
134
+
---
135
+
136
+
## Routes Become HTML Files {#routes-become-html-files}
137
+
138
+
Every route in Docusaurus compiles into a **static HTML file** during build. For instance, the route `/docs/advanced/routing` maps to:
139
+
140
+
```
141
+
/build/docs/advanced/routing/index.html
142
+
```
143
+
144
+
If `trailingSlash` is disabled, the same route becomes `routing.html`.
145
+
146
+
This allows hosting on any static server (like GitHub Pages or Vercel) — Docusaurus handles **server-side rendering → static HTML conversion** automatically.
147
+
148
+
### Example
149
+
150
+
```bash
151
+
build/
152
+
├── docs/
153
+
│ └── advanced/
154
+
│ └── routing/
155
+
│ └── index.html # /docs/advanced/routing
156
+
└── index.html # /
157
+
```
158
+
159
+
When using a custom `baseUrl`, ensure assets resolve correctly (e.g., `/base/assets/js/...`).
160
+
161
+
---
162
+
163
+
## Generating and Accessing Routes {#generating-and-accessing-routes}
164
+
165
+
Use the `addRoute` lifecycle method to programmatically add routes:
166
+
167
+
```js title="plugin-example.js"
168
+
actions.addRoute({
169
+
path:"/custom",
170
+
component:"@site/src/pages/CustomPage.js",
171
+
});
172
+
```
173
+
174
+
All routes are aggregated in `.docusaurus/routes.js`.
175
+
You can inspect them in the [Debug Routes Panel](/__docusaurus/debug/routes).
176
+
177
+
### Accessing Routes in React
178
+
179
+
You can access route data using `@docusaurus/router`, a wrapper around React Router.
180
+
181
+
```jsx title="RouteInfo.js"
182
+
importReactfrom"react";
183
+
import { useLocation } from"@docusaurus/router";
184
+
185
+
exportfunctionPageRoute() {
186
+
constlocation=useLocation();
187
+
return (
188
+
<span>
189
+
You are currently on <code>{location.pathname}</code>
190
+
</span>
191
+
);
192
+
}
193
+
```
194
+
195
+
```mdx-code-block
196
+
<BrowserWindow>
197
+
<span>
198
+
You are currently on <code>{location.pathname}</code>
Because Docusaurus is an SPA, it handles navigation through React Router. However, if you link to static HTML files that aren’t part of Docusaurus routes, use the special `pathname://` protocol to perform a **non-SPA redirect**.
- Docusaurus follows a **SPA routing system** built on React Router.
234
+
- Every content plugin defines its **route base path**.
235
+
-**Docs** support **nested and versioned** routes.
236
+
- URLs map directly from files but can be customized using `slug`.
237
+
- During build, routes become **static HTML files** for deployment.
238
+
- Use `pathname://` for non-SPA links or static assets.
239
+
240
+
With this routing power, our **CodeHarborHub** site can scale efficiently — from a simple landing page to a complex multi-version documentation ecosystem.
0 commit comments