URL Routing
Docusaurus uses file-based routing combined with document metadata to determine the final URL for a documentation page.
Understanding how routes are calculated is useful when:
- customizing URLs
- improving SEO readability
- migrating an existing documentation structure
- debugging broken links
This page explains how Docusaurus determines a document’s route and how slugs interact with IDs, filenames, and directory structure.
File-Based Routing in Docusaurus
In a typical docs setup, the route is composed of several parts:
<site-url>/<routeBasePath>/<directory structure>/<doc route segment>
For example:
technical/languages/oop-and-functional/python/pandas/pandas-mutability-illusion-of-pointers.md
With this plugin configuration:
{
id: "docs-t",
path: "technical",
routeBasePath: "technical"
}
the final route becomes:
https://thomasrones.com/technical/languages/oop-and-functional/python/pandas/<doc-segment>
The question then becomes:
How does Docusaurus determine <doc-segment>?
How Docusaurus Calculates a Doc Route
The final route segment is determined roughly in the following priority order.
1. slug (Highest Priority)
If a document defines a slug in front matter, that slug determines the route.
Example:
---
slug: "pandas-mutability-illusion-of-pointers"
---
Final route:
/technical/languages/oop-and-functional/python/pandas/pandas-mutability-illusion-of-pointers
You do not need to specify the full path. If the slug is relative, Docusaurus preserves the directory-derived portion of the route.
Example:
slug: "pandas-mutability-illusion-of-pointers"
Result:
/technical/languages/oop-and-functional/python/pandas/pandas-mutability-illusion-of-pointers
This is useful when you only want to override the final segment.
2. id
If no slug is provided, Docusaurus uses the document id.
Example:
---
id: a01a96df-f3f2-478a-9ca7-3cd37490e630
---
Final route:
/technical/languages/oop-and-functional/python/pandas/a01a96df-f3f2-478a-9ca7-3cd37490e630
This is why many sites that use UUID IDs end up with UUID-looking URLs.
3. Filename
If neither slug nor id are defined, Docusaurus falls back to the filename.
Example:
important-basics.md
Route:
/technical/languages/oop-and-functional/python/pandas/important-basics
Route Composition Summary
Putting it all together:
final route =
routeBasePath
+ folder structure
+ (slug OR id OR filename)
Priority order:
slug
↓
id
↓
filename
Why Relative Slugs Are Useful
Relative slugs let you modify the last segment of the route without rewriting the entire path.
Instead of writing:
slug: /languages/oop-and-functional/python/pandas/pandas-mutability-illusion-of-pointers
you can simply write:
slug: pandas-mutability-illusion-of-pointers
Docusaurus preserves the rest of the route automatically.
This allows you to:
- keep your existing directory taxonomy
- remove ugly UUID endings
- test SEO-friendly routes
- minimize link breakage risk
Example
File:
technical/languages/oop-and-functional/python/pandas/pandas-mutability-and-the-illusion-of-pointers.md
Front matter:
---
id: a01a96df-f3f2-478a-9ca7-3cd37490e630
slug: pandas-mutability-illusion-of-pointers
---
Resulting route:
https://thomasrones.com/technical/languages/oop-and-functional/python/pandas/pandas-mutability-illusion-of-pointers
What Can Break When Changing Slugs
Changing a slug changes the route.
This can break:
- navbar links
- footer links
- hardcoded markdown links
- external backlinks
- search engine indexed URLs
The sidebar itself is unaffected because it references the document ID internally.
Suggested Strategy
If your site currently uses UUID IDs:
- Keep IDs stable
- Add slugs only to important docs
- Prefer relative slugs
- Avoid rewriting the entire route
- Audit hardcoded links
This allows incremental improvement without restructuring the whole documentation system.
Key Takeaway
Docusaurus routes are determined by a combination of configuration, directory structure, and document metadata.
The effective priority is:
slug → id → filename
Understanding this makes it much easier to control URLs while still benefiting from autogenerated sidebars and file-based routing.