feat(core): hash router option - browse site offline (experimental)

[slorber]

Motivation

New site config option:

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

See also my comment here that presents the feature: #3825 (comment)

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/.

hash router + baseUrl = bugs 🐛

If you plan to use the hash router, we'd recommend using it without a /baseUrl/ param. It probably does not make sense to use it anyway, because we try to make all links relative to make it work with the file:// protocol, so hosting it on any subpath should work fine.

There's also a bit of ambiguity because baseUrl /docusaurus/ would mean that you access the app through a link such as https://myUrl.com/#/baseUrl/, and not https://myUrl.com/baseUrl/#/ like most of you would probably expect. There's probably no good reason to host the app under a hash subpath.

Unless someone comes up with a strong motivation for hash router + baseUrl, we are likely to forbid/ignore the usage of a baseUrl with hash router in the future. So please share your use case in the comments!

Test Plan

Unit tests + new CI workflow

That's so easy to dogfood, unfortunately. This has quite a large API surface. We probably need new Playwright tests to ensure this keeps working reliably over time, in particular the offline mode using file:// protocol.

To make it easier to manually review the hash router, we:

• Upload a GitHub website artifact that can be downloaded and browsed locally with file://
• We also deploy it to our old GitHub Pages: https://facebook.github.io/docusaurus/#/

Test links

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

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	7cf6500
🔍 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]

⚡️ 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]

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！