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！

[1181214171]

After a series of studies, I believe that hash routing is the ideal solution for my needs, but I found that it might have some incompatibility with i18n? Do you know anything about this?

[slorber]

@1181214171

I found that it might have some incompatibility with i18n?

What did you found exactly? If you do not share what you found, you make it harder for us to help you.

The Hash Router does not support well using a base URL. And building your site for multiple locales at once is going to add an automatic /<locale>/ base url and cause problems. For the locales hosted under a base url (not the default one).

For example this doesn't work well for our own website:

DOCUSAURUS_ROUTER=hash yarn build:website --locale en --locale fr
yarn serve:website

But if you build one locale after another, then it works fine because the French locale gets hosted at http://localhost:3000/#/ instead of http://localhost:3000/fr/#/

DOCUSAURUS_ROUTER=hash yarn build:website --locale fr
yarn serve:website

[1181214171]

@1181214171

我发现它可能与 i18n 不兼容？

你到底发现了什么？如果你不分享你的发现，我们就更难帮助你。

Hash Router 无法很好地支持使用基本 URL。同时为多个地区构建网站将添加自动/<locale>/基本 URL 并导致问题。对于在基本 URL（而非默认 URL）下托管的地区。

例如，这对于我们自己的网站来说效果不佳：

DOCUSAURUS_ROUTER=hash yarn build:website --locale en --locale fr
yarn serve:website

但如果你建立一个又一个的语言环境，那么它就可以正常工作，因为法语语言环境托管http://localhost:3000/#/在http://localhost:3000/fr/#/

DOCUSAURUS_ROUTER=hash yarn build:website --locale fr
yarn serve:website

Thank you for your detailed response. Now let me describe the issue I'm encountering in detail.

First, after adding the hash router and executing the build, everything seemed perfect. I obtained an offline document that could be compressed and distributed. However, when I tried to switch languages, I found that it couldn't navigate to the correct page.

For example, my normal page path is: file:///D:/Docs/hashrouter/build/index.html#/, but when I tried to switch to the zh, ko, or ja versions, the path pointed to file:///D:/zh/.

Initially, I thought there might be an issue with my i18n configuration, so I downloaded the official example document archive "website-hash-router-archive.zip".

The standard path at this point is: file:///D:/Docs/website-hash-router-archive/index.html#/. When I tried to switch languages, the path similarly changed to file:///D:/fr/.

I'm wondering if the hash router requires some additional configuration for i18n, or if there's an issue with my i18n settings causing this?

To add, my requirements are very simple. My document is for local offline use only, supports multiple languages, and is searchable, that's all.

[slorber]

You cannot "switch" language with the Hash Router because we do not have support for base URL.

You have to remove the locale dropdown, build a different site per locale, and let users download the site in the language they care about.

By the way, it is also more optional: if I'm French I don't want to download the Chinese site for example.

[1181214171]

You cannot "switch" language with the Hash Router because we do not have support for base URL.

You have to remove the locale dropdown, build a different site per locale, and let users download the site in the language they care about.

By the way, it is also more optional: if I'm French I don't want to download the Chinese site for example.

Thank you very much for your detailed explanation! I will continue to package independently for now. But by the way, will it be possible to switch languages while using hash router in the future?