feat(core): hash router (experimental)

[slorber]

Motivation

New site config option:

export default {
  future: {
    experimental_router: 'hash', // default to "browser"
  }
}

The hash router is useful in rare cases, and will:

• use browser URLs starting with a /#/ prefix
• opt-out of static site generation
• only emit a single index.html file
• only do client-side routing and rendering

In practice, all the URLs will load a single index.html empty shell file, and will look like:

• https://docusaurus.io/#/
• https://docusaurus.io/#/docs
• https://docusaurus.io/#/docs/myDoc?age=42#someHeading

The motivation for this new router feature is to fix #3825, and allow distributing a Docusaurus site as a standalone .zip archive that can be browsed without a web server, using the file:// protocol (ex file://path/to/site/index.html)

Note using the hash router will disable the following features that probably do not make much sense under this new mode:

• Sitemap
• Blog feeds
• OpenSearch file
• Client redirects
• PWA

EXPERIMENTAL FEATURE:

The hash router is likely to contain unhandled edge cases. Notably if you plan to use the file:// protocol, or have a site /baseUrl/.

If you plan to use it, we'd recommend using it without a /baseUrl/ param.

Test Plan

Unit tests + new CI workflow

Not easy to dogfood unfortunately, and this has a quite large API surface spanning

Test links

Docs: https://deploy-preview-9859--docusaurus-2.netlify.app/docs/api/docusaurus-config/#future

Test links when hash router is turned on:

• Home https://deploy-preview-9859--docusaurus-2.netlify.app/
• Doc: https://deploy-preview-9859--docusaurus-2.netlify.app/#/docs/markdown-features/tabs/
• Doc heading: https://deploy-preview-9859--docusaurus-2.netlify.app/#/docs/markdown-features/tabs/#query-string
• Doc heading + search: https://deploy-preview-9859--docusaurus-2.netlify.app/#/docs/markdown-features/tabs/?current-os=ios#query-string
• Blog: https://deploy-preview-9859--docusaurus-2.netlify.app/#/blog/releases/3.1/
• Blog heading: https://deploy-preview-9859--docusaurus-2.netlify.app/#/blog/releases/3.1/#parsefrontmatter-hook

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	db860a8
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/664796fc4cfe09000880e3dc
😎 Deploy Preview	https://deploy-preview-9859--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 72	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 61	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 77	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 68	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 63	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 72	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 77	🟢 100	🟢 100	🟢 90	🟠 88	Report

[github-actions]

Size Change: +845 B (+0.05%)

Total Size: 1.72 MB

Filename	Size	Change
website/.docusaurus/docusaurus.config.mjs	26.9 kB	+38 B (+0.14%)
website/build/assets/js/main.********.js	854 kB	+807 B (+0.09%)

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/codeTranslations.json	2 B
website/.docusaurus/globalData.json	107 kB
website/.docusaurus/i18n.json	930 B
website/.docusaurus/registry.js	275 kB
website/.docusaurus/routes.js	179 kB
website/.docusaurus/routesChunkNames.json	119 kB
website/.docusaurus/site-metadata.json	2.17 kB
website/build/assets/css/styles.********.css	112 kB
website/build/index.html	38.1 kB

_{compressed-size-action}

[zayne-wang]

Looking forward that this will be release in the future！

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	1 changed	May 17, 2024, 5:49 PM