From 9267fc0adf12c147b9654471e61b929ae79a6a7f Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 8 Oct 2025 18:15:39 +0530 Subject: [PATCH 1/6] try to use new way --- docs/advanced/routing.mdx | 236 +++++++++++++++++++++++++++++++++++++- 1 file changed, 235 insertions(+), 1 deletion(-) diff --git a/docs/advanced/routing.mdx b/docs/advanced/routing.mdx index 05a45c989..b9954f120 100644 --- a/docs/advanced/routing.mdx +++ b/docs/advanced/routing.mdx @@ -3,4 +3,238 @@ title: Advanced Routing description: "Learn how Docusaurus handles routing across docs, blog, and pages. Understand route structure, path mapping, and SPA transitions." sidebar_label: Routing tags: [routing, docusaurus, react-router, docs, pages, blog] ---- \ No newline at end of file +--- + +```mdx-code-block +import Link from '@docusaurus/Link'; +import {useActiveDocContext} from '@docusaurus/plugin-content-docs/client'; +import {useLocation} from '@docusaurus/router'; +import BrowserOnly from '@docusaurus/BrowserOnly'; +``` + +Docusaurus uses a **single-page application (SPA)** routing system — meaning every route corresponds to **one component**. + +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. + +--- + +## Routing in Content Plugins {#routing-in-content-plugins} + +Each content plugin defines a `routeBasePath`, which tells Docusaurus **where to mount routes**. + +- **Docs plugin:** `/docs` by default +- **Blog plugin:** `/blog` +- **Pages plugin:** `/` + +Here’s how these routes connect in the URL hierarchy: + +```mermaid +graph LR; + A(["https://codeharborhub.github.io/"]) + B(["/base-url/"]) + C(["/docs/"]) + D(["/blog/"]) + E(["/"]) + F["Docs Routes"] + G["Blog Routes"] + H["Page Routes"] + A---B; + B---C; + B---D; + B---E; + C---F; + D---G; + E---H; +``` + +When a user visits `/docs/configuration`, Docusaurus finds the `/docs` branch, and then loads the corresponding document route. + +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. + +--- + +## Pages Routing {#pages-routing} + +**Pages** are the simplest form of routes — file paths directly map to URLs. +For example: + +``` +src/pages/about.mdx → /about +src/pages/index.js → / +``` + +- Markdown pages render using `@theme/MDXPage`. +- React components render directly as route components. + +See [Creating Pages](../guides/creating-pages.mdx#routing) for more details. + +--- + +## Blog Routing {#blog-routing} + +The blog plugin auto-generates several types of routes: + +| Route Type | Example URL | Customizable Option | Component | +| ------------------- | ----------------------------- | ------------------- | -------------------------- | +| **Posts List** | `/`, `/page/2`, `/page/3` | `pageBasePath` | `@theme/BlogListPage` | +| **Individual Post** | `/2025/10/08/launch-post` | `slug` front matter | `@theme/BlogPostPage` | +| **Tags List** | `/tags` | `tagsBasePath` | `@theme/BlogTagsListPage` | +| **Tag Pages** | `/tags/education`, `/tags/ai` | `permalink` in tag | `@theme/BlogTagsPostsPage` | +| **Archive Page** | `/archive` | `archiveBasePath` | `@theme/BlogArchivePage` | + +Each route is generated automatically, but you can override any path with custom front matter. + +--- + +## Docs Routing {#docs-routing} + +Docs routing is **hierarchical** and **versioned**. Each version has its own route tree, sidebar, and context. + +For example: + +``` +/docs/ → Current version +/docs/next → Next version +/docs/1.0.0 → Past version +``` + +This allows seamless version switching while preserving sidebar state. + +```mdx-code-block +export const URLPath = () => {useLocation().pathname}; +export const FilePath = () => { + const currentVersion = useActiveDocContext('default').activeVersion.name; + return {currentVersion === 'current' ? './docs/' : `./versioned_docs/version-${currentVersion}/`}advanced/routing.md; +}; +``` + +This page, {()=> }, is generated from {()=> }. The doc content is displayed inside `@theme/DocPage`, which manages layout, sidebar, and navigation. + +--- + +## File Paths vs URL Paths {#file-paths-and-url-paths} + +In Docusaurus, **file paths map to URL paths**, unless overridden using the `slug` front matter. + +### Example Mapping + +| File Path | URL Path | +| ------------------------------ | ------------------------- | +| `./docs/advanced/routing.md` | `/docs/advanced/routing` | +| `./blog/2025-10-08-launch.mdx` | `/blog/2025/10/08/launch` | + +### Rules for Markdown Links + +- `@site` prefix → Asset file path +- `http(s)://` prefix → External URL +- No extension → URL path +- `.md(x)` extension → Converts file path to URL +- Other extensions → Treated as [assets](../guides/markdown-features/markdown-features-assets.mdx) + +--- + +## Routes Become HTML Files {#routes-become-html-files} + +Every route in Docusaurus compiles into a **static HTML file** during build. For instance, the route `/docs/advanced/routing` maps to: + +``` +/build/docs/advanced/routing/index.html +``` + +If `trailingSlash` is disabled, the same route becomes `routing.html`. + +This allows hosting on any static server (like GitHub Pages or Vercel) — Docusaurus handles **server-side rendering → static HTML conversion** automatically. + +### Example + +```bash +build/ +├── docs/ +│ └── advanced/ +│ └── routing/ +│ └── index.html # /docs/advanced/routing +└── index.html # / +``` + +When using a custom `baseUrl`, ensure assets resolve correctly (e.g., `/base/assets/js/...`). + +--- + +## Generating and Accessing Routes {#generating-and-accessing-routes} + +Use the `addRoute` lifecycle method to programmatically add routes: + +```js title="plugin-example.js" +actions.addRoute({ + path: "/custom", + component: "@site/src/pages/CustomPage.js", +}); +``` + +All routes are aggregated in `.docusaurus/routes.js`. +You can inspect them in the [Debug Routes Panel](/__docusaurus/debug/routes). + +### Accessing Routes in React + +You can access route data using `@docusaurus/router`, a wrapper around React Router. + +```jsx title="RouteInfo.js" +import React from "react"; +import { useLocation } from "@docusaurus/router"; + +export function PageRoute() { + const location = useLocation(); + return ( + + You are currently on {location.pathname} + + ); +} +``` + +```mdx-code-block + + + You are currently on {location.pathname} + + +``` + +--- + +## Escaping SPA Redirects {#escaping-from-spa-redirects} + +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**. + +```md +- [pathname:///static-page](pathname:///static-page) +``` + + + +- [`pathname:///static-page`](pathname:///static-page) + + + +This ensures Docusaurus doesn’t attempt to render missing routes or show a 404 page. + +You can also use `pathname://` for static assets: + +```md title="my-doc.md" +![Static image](pathname:///img/codeharborhub-banner.png) + +[Download PDF](pathname:///files/tutorial.pdf) +``` + +--- + +## Summary + +- Docusaurus follows a **SPA routing system** built on React Router. +- Every content plugin defines its **route base path**. +- **Docs** support **nested and versioned** routes. +- URLs map directly from files but can be customized using `slug`. +- During build, routes become **static HTML files** for deployment. +- Use `pathname://` for non-SPA links or static assets. + +With this routing power, our **CodeHarborHub** site can scale efficiently — from a simple landing page to a complex multi-version documentation ecosystem. \ No newline at end of file From d874d9c64da06b5e57aedc0a4a3cc87870855efb Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 8 Oct 2025 18:25:27 +0530 Subject: [PATCH 2/6] try to fix bug --- docs/advanced/routing.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/advanced/routing.mdx b/docs/advanced/routing.mdx index b9954f120..d103bf8a3 100644 --- a/docs/advanced/routing.mdx +++ b/docs/advanced/routing.mdx @@ -6,7 +6,6 @@ tags: [routing, docusaurus, react-router, docs, pages, blog] --- ```mdx-code-block -import Link from '@docusaurus/Link'; import {useActiveDocContext} from '@docusaurus/plugin-content-docs/client'; import {useLocation} from '@docusaurus/router'; import BrowserOnly from '@docusaurus/BrowserOnly'; @@ -101,14 +100,14 @@ For example: This allows seamless version switching while preserving sidebar state. ```mdx-code-block -export const URLPath = () => {useLocation().pathname}; -export const FilePath = () => { +export const URLPath = () => {()=>{useLocation().pathname}} +export const FilePath = () => {() => { const currentVersion = useActiveDocContext('default').activeVersion.name; return {currentVersion === 'current' ? './docs/' : `./versioned_docs/version-${currentVersion}/`}advanced/routing.md; -}; +}} ``` -This page, {()=> }, is generated from {()=> }. The doc content is displayed inside `@theme/DocPage`, which manages layout, sidebar, and navigation. +This page, , is generated from . The doc content is displayed inside `@theme/DocPage`, which manages layout, sidebar, and navigation. --- From 3c738904404ca3c565469aab8e7e5bef68f7443f Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 8 Oct 2025 18:41:56 +0530 Subject: [PATCH 3/6] try to fix bug --- docs/advanced/routing.mdx | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/advanced/routing.mdx b/docs/advanced/routing.mdx index d103bf8a3..f6ad1f9e2 100644 --- a/docs/advanced/routing.mdx +++ b/docs/advanced/routing.mdx @@ -209,11 +209,6 @@ Because Docusaurus is an SPA, it handles navigation through React Router. Howeve - [pathname:///static-page](pathname:///static-page) ``` - - -- [`pathname:///static-page`](pathname:///static-page) - - This ensures Docusaurus doesn’t attempt to render missing routes or show a 404 page. From 80e5b2bda9eead853c388136f5add9d354b75206 Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 8 Oct 2025 18:46:56 +0530 Subject: [PATCH 4/6] try to fix bug --- docs/advanced/routing.mdx | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/advanced/routing.mdx b/docs/advanced/routing.mdx index f6ad1f9e2..fb44dd7a6 100644 --- a/docs/advanced/routing.mdx +++ b/docs/advanced/routing.mdx @@ -191,13 +191,7 @@ export function PageRoute() { } ``` -```mdx-code-block - - - You are currently on {location.pathname} - - -``` + --- @@ -209,6 +203,11 @@ Because Docusaurus is an SPA, it handles navigation through React Router. Howeve - [pathname:///static-page](pathname:///static-page) ``` + + +- [`pathname:///static-page`](pathname:///static-page) + + This ensures Docusaurus doesn’t attempt to render missing routes or show a 404 page. @@ -231,4 +230,4 @@ You can also use `pathname://` for static assets: - During build, routes become **static HTML files** for deployment. - Use `pathname://` for non-SPA links or static assets. -With this routing power, our **CodeHarborHub** site can scale efficiently — from a simple landing page to a complex multi-version documentation ecosystem. \ No newline at end of file +With this routing power, our **CodeHarborHub** site can scale efficiently — from a simple landing page to a complex multi-version documentation ecosystem. From 1c0c234e720265b032e22b961342e58d62334583 Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 8 Oct 2025 18:50:22 +0530 Subject: [PATCH 5/6] Fixed Bug --- docs/advanced/routing.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/advanced/routing.mdx b/docs/advanced/routing.mdx index fb44dd7a6..285bfa617 100644 --- a/docs/advanced/routing.mdx +++ b/docs/advanced/routing.mdx @@ -191,7 +191,13 @@ export function PageRoute() { } ``` - + + + { + ()=> You are currently on {location.pathname} + } + --- From 3ecf0d7f2b44e3880d65b8fddedbcbf4eeefaa0d Mon Sep 17 00:00:00 2001 From: unknown Date: Wed, 8 Oct 2025 18:52:10 +0530 Subject: [PATCH 6/6] Fixed Bug --- docs/advanced/routing.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced/routing.mdx b/docs/advanced/routing.mdx index 285bfa617..4507ab724 100644 --- a/docs/advanced/routing.mdx +++ b/docs/advanced/routing.mdx @@ -196,7 +196,7 @@ export function PageRoute() { { ()=> You are currently on {location.pathname} } - ---