Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 53 commits into from
May 19, 2024

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented Feb 16, 2024

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:

Test links

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

@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Feb 16, 2024
Copy link

netlify bot commented Feb 16, 2024

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

QR Code

Use your smartphone camera to open QR code link.

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

Copy link

github-actions bot commented Feb 16, 2024

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

Copy link

github-actions bot commented Feb 16, 2024

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

@slorber slorber added pr: new feature This PR adds a new API or behavior. to backport This PR is planned to be backported to a stable version of Docusaurus labels Feb 22, 2024
@zayne-wang
Copy link

Looking forward that this will be release in the future!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Argos Add this label to run UI visual regression tests. See argos.yml GH action. CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Option to generate offline static HTML files usable without server
5 participants