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 https://github.com/facebook/docusaurus/issues/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[bot]]

✅ [V2]

Name	Link
🔨 Latest commit	7cf650018f926a9afd60722d1eafcd611933a06e
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/6649b7a16337f20009fca4e9
😎 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[bot]]

⚡️ Lighthouse report for the deploy preview of this PR

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

[github-actions[bot]]

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}

[zachary-wang12]

Looking forward that this will be release in the future！

[lebalz]

What is the state of this? Is there anything we could help with to get this merged?

[slorber]

Busy on other things.

I'll try to get this merged for the next minor/major.

The POC is working but I'm not sure it's super robust regarding edge cases.

Maybe we could ship it as experimental first, and get early adopter feedback to fix bugs.

[argos-ci[bot]]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	1 changed	May 19, 2024, 8:33 AM

[ZenaMel]

This is awesome! Can't wait to test it out with my team (we have multiple use cases for this). I'll be sure to forward any issues we find. Cool stuff, for real.