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

Author: slorber

.github/workflows/build-hash-router.yml

@@ -0,0 +1,60 @@
+name: Build Hash Router
+
+on:
+  pull_request:
+    branches:
+      - main
+      - docusaurus-v**
+    paths:
+      - packages/**
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Hash Router
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - name: Set up Node
+        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        with:
+          node-version: '18'
+          cache: yarn
+      - name: Installation
+        run: yarn
+      - name: Build Hash Router
+        run: yarn build:website:fast
+        env:
+          DOCUSAURUS_ROUTER: 'hash'
+          BASE_URL: '/docusaurus/' # GH pages deploys under https://facebook.github.io/docusaurus/
+      - name: Upload Website artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: website-hash-router-archive
+          path: website/build
+      - name: Upload Website Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/build
+
+  # See https://docusaurus.io/docs/deployment#triggering-deployment-with-github-actions
+  deploy:
+    name: Deploy to GitHub Pages
+    if: ${{ github.event_name != 'pull_request' && github.ref_name == 'main')}}
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

packages/docusaurus-plugin-client-redirects/src/index.ts

@@ -6,6 +6,7 @@
  */
 
 import {addLeadingSlash, removePrefix} from '@docusaurus/utils-common';
+import logger from '@docusaurus/logger';
 import collectRedirects from './collectRedirects';
 import writeRedirectFiles, {
   toRedirectFiles,
@@ -15,14 +16,24 @@ import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {PluginContext, RedirectItem} from './types';
 import type {PluginOptions, Options} from './options';
 
+const PluginName = 'docusaurus-plugin-client-redirects';
+
 export default function pluginClientRedirectsPages(
   context: LoadContext,
   options: PluginOptions,
 ): Plugin<void> {
   const {trailingSlash} = context.siteConfig;
+  const router = context.siteConfig.future.experimental_router;
+
+  if (router === 'hash') {
+    logger.warn(
+      `${PluginName} does not support the Hash Router and will be disabled.`,
+    );
+    return {name: PluginName};
+  }
 
   return {
-    name: 'docusaurus-plugin-client-redirects',
+    name: PluginName,
     async postBuild(props) {
       const pluginContext: PluginContext = {
         relativeRoutesPaths: props.routesPaths.map(

packages/docusaurus-plugin-content-blog/src/__tests__/index.test.ts

@@ -106,6 +106,7 @@ const getPlugin = async (
     baseUrl: '/',
     url: 'https://docusaurus.io',
     markdown,
+    future: {},
   } as DocusaurusConfig;
   return pluginContentBlog(
     {

packages/docusaurus-plugin-content-blog/src/feed.ts

@@ -16,7 +16,7 @@ import {
   applyTrailingSlash,
 } from '@docusaurus/utils-common';
 import {load as cheerioLoad} from 'cheerio';
-import type {DocusaurusConfig} from '@docusaurus/types';
+import type {DocusaurusConfig, HtmlTags, LoadContext} from '@docusaurus/types';
 import type {
   FeedType,
   PluginOptions,
@@ -254,3 +254,59 @@ export async function createBlogFeedFiles({
     ),
   );
 }
+
+export function createFeedHtmlHeadTags({
+  context,
+  options,
+}: {
+  context: LoadContext;
+  options: PluginOptions;
+}): HtmlTags {
+  const feedTypes = options.feedOptions.type;
+  if (!feedTypes) {
+    return [];
+  }
+  const feedTitle = options.feedOptions.title ?? context.siteConfig.title;
+  const feedsConfig = {
+    rss: {
+      type: 'application/rss+xml',
+      path: 'rss.xml',
+      title: `${feedTitle} RSS Feed`,
+    },
+    atom: {
+      type: 'application/atom+xml',
+      path: 'atom.xml',
+      title: `${feedTitle} Atom Feed`,
+    },
+    json: {
+      type: 'application/json',
+      path: 'feed.json',
+      title: `${feedTitle} JSON Feed`,
+    },
+  };
+  const headTags: HtmlTags = [];
+
+  feedTypes.forEach((feedType) => {
+    const {
+      type,
+      path: feedConfigPath,
+      title: feedConfigTitle,
+    } = feedsConfig[feedType];
+
+    headTags.push({
+      tagName: 'link',
+      attributes: {
+        rel: 'alternate',
+        type,
+        href: normalizeUrl([
+          context.siteConfig.baseUrl,
+          options.routeBasePath,
+          feedConfigPath,
+        ]),
+        title: feedConfigTitle,
+      },
+    });
+  });
+
+  return headTags;
+}

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -29,11 +29,11 @@ import {
 } from './blogUtils';
 import footnoteIDFixer from './remark/footnoteIDFixer';
 import {translateContent, getTranslationFiles} from './translations';
-import {createBlogFeedFiles} from './feed';
+import {createBlogFeedFiles, createFeedHtmlHeadTags} from './feed';
 
 import {createAllRoutes} from './routes';
 import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
-import type {LoadContext, Plugin, HtmlTags} from '@docusaurus/types';
+import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {
   PluginOptions,
   BlogPostFrontMatter,
@@ -44,6 +44,8 @@ import type {
   BlogPaginated,
 } from '@docusaurus/plugin-content-blog';
 
+const PluginName = 'docusaurus-plugin-content-blog';
+
 export default async function pluginContentBlog(
   context: LoadContext,
   options: PluginOptions,
@@ -55,22 +57,29 @@ export default async function pluginContentBlog(
     localizationDir,
     i18n: {currentLocale},
   } = context;
+
+  const router = siteConfig.future.experimental_router;
+  const isBlogFeedDisabledBecauseOfHashRouter =
+    router === 'hash' && !!options.feedOptions.type;
+  if (isBlogFeedDisabledBecauseOfHashRouter) {
+    logger.warn(
+      `${PluginName} feed feature does not support the Hash Router. Feeds won't be generated.`,
+    );
+  }
+
   const {onBrokenMarkdownLinks, baseUrl} = siteConfig;
 
   const contentPaths: BlogContentPaths = {
     contentPath: path.resolve(siteDir, options.path),
     contentPathLocalized: getPluginI18nPath({
       localizationDir,
-      pluginName: 'docusaurus-plugin-content-blog',
+      pluginName: PluginName,
       pluginId: options.id,
     }),
   };
   const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
 
-  const pluginDataDirRoot = path.join(
-    generatedFilesDir,
-    'docusaurus-plugin-content-blog',
-  );
+  const pluginDataDirRoot = path.join(generatedFilesDir, PluginName);
   const dataDir = path.join(pluginDataDirRoot, pluginId);
   // TODO Docusaurus v4 breaking change
   //  module aliasing should be automatic
@@ -84,7 +93,7 @@ export default async function pluginContentBlog(
   });
 
   return {
-    name: 'docusaurus-plugin-content-blog',
+    name: PluginName,
 
     getPathsToWatch() {
       const {include} = options;
@@ -295,15 +304,16 @@ export default async function pluginContentBlog(
     },
 
     async postBuild({outDir, content}) {
-      if (!options.feedOptions.type) {
-        return;
-      }
-      const {blogPosts} = content;
-      if (!blogPosts.length) {
+      if (
+        !content.blogPosts.length ||
+        !options.feedOptions.type ||
+        isBlogFeedDisabledBecauseOfHashRouter
+      ) {
         return;
       }
+
       await createBlogFeedFiles({
-        blogPosts,
+        blogPosts: content.blogPosts,
         options,
         outDir,
         siteConfig,
@@ -312,56 +322,15 @@ export default async function pluginContentBlog(
     },
 
     injectHtmlTags({content}) {
-      if (!content.blogPosts.length || !options.feedOptions.type) {
+      if (
+        !content.blogPosts.length ||
+        !options.feedOptions.type ||
+        isBlogFeedDisabledBecauseOfHashRouter
+      ) {
         return {};
       }
 
-      const feedTypes = options.feedOptions.type;
-      const feedTitle = options.feedOptions.title ?? context.siteConfig.title;
-      const feedsConfig = {
-        rss: {
-          type: 'application/rss+xml',
-          path: 'rss.xml',
-          title: `${feedTitle} RSS Feed`,
-        },
-        atom: {
-          type: 'application/atom+xml',
-          path: 'atom.xml',
-          title: `${feedTitle} Atom Feed`,
-        },
-        json: {
-          type: 'application/json',
-          path: 'feed.json',
-          title: `${feedTitle} JSON Feed`,
-        },
-      };
-      const headTags: HtmlTags = [];
-
-      feedTypes.forEach((feedType) => {
-        const {
-          type,
-          path: feedConfigPath,
-          title: feedConfigTitle,
-        } = feedsConfig[feedType];
-
-        headTags.push({
-          tagName: 'link',
-          attributes: {
-            rel: 'alternate',
-            type,
-            href: normalizeUrl([
-              baseUrl,
-              options.routeBasePath,
-              feedConfigPath,
-            ]),
-            title: feedConfigTitle,
-          },
-        });
-      });
-
-      return {
-        headTags,
-      };
+      return {headTags: createFeedHtmlHeadTags({context, options})};
     },
   };
 }

packages/docusaurus-plugin-pwa/package.json

@@ -23,6 +23,7 @@
     "@babel/core": "^7.23.3",
     "@babel/preset-env": "^7.23.3",
     "@docusaurus/core": "3.3.2",
+    "@docusaurus/logger": "3.3.2",
     "@docusaurus/theme-common": "3.3.2",
     "@docusaurus/theme-translations": "3.3.2",
     "@docusaurus/types": "3.3.2",

packages/docusaurus-plugin-pwa/src/index.ts

@@ -11,11 +11,14 @@ import WebpackBar from 'webpackbar';
 import Terser from 'terser-webpack-plugin';
 import {injectManifest} from 'workbox-build';
 import {normalizeUrl} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
 import {compile} from '@docusaurus/core/lib/webpack/utils';
 import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
 import type {HtmlTags, LoadContext, Plugin} from '@docusaurus/types';
 import type {PluginOptions} from '@docusaurus/plugin-pwa';
 
+const PluginName = 'docusaurus-plugin-pwa';
+
 const isProd = process.env.NODE_ENV === 'production';
 
 function getSWBabelLoader() {
@@ -47,6 +50,7 @@ export default function pluginPWA(
     outDir,
     baseUrl,
     i18n: {currentLocale},
+    siteConfig,
   } = context;
   const {
     debug,
@@ -57,8 +61,15 @@ export default function pluginPWA(
     swRegister,
   } = options;
 
+  if (siteConfig.future.experimental_router === 'hash') {
+    logger.warn(
+      `${PluginName} does not support the Hash Router and will be disabled.`,
+    );
+    return {name: PluginName};
+  }
+
   return {
-    name: 'docusaurus-plugin-pwa',
+    name: PluginName,
 
     getThemePath() {
       return '../lib/theme';

packages/docusaurus-plugin-sitemap/src/index.ts

@@ -12,12 +12,21 @@ import createSitemap from './createSitemap';
 import type {PluginOptions, Options} from './options';
 import type {LoadContext, Plugin} from '@docusaurus/types';
 
+const PluginName = 'docusaurus-plugin-sitemap';
+
 export default function pluginSitemap(
   context: LoadContext,
   options: PluginOptions,
 ): Plugin<void> {
+  if (context.siteConfig.future.experimental_router === 'hash') {
+    logger.warn(
+      `${PluginName} does not support the Hash Router and will be disabled.`,
+    );
+    return {name: PluginName};
+  }
+
   return {
-    name: 'docusaurus-plugin-sitemap',
+    name: PluginName,
 
     async postBuild({siteConfig, routes, outDir, head}) {
       if (siteConfig.noIndex) {