fix(v2): allow using classic theme/preset without the docs plugin (#3382)

* deprecated nextVersionLabel option

* useActivePlugin failfast option

* remove deprecated option nextVersionLabel

* routeBasePath: '' should be forbidden

* routeBasePath: '' should be forbidden

* Docs: do not show version badge if there is only 1 version: https://github.com/facebook/docusaurus/issues/3362

* allow sidebars file to not exist: fallback to empty sidebars
https://githu.com/facebook/docusaurus/issues/3366

* Ability to use classic theme/preset while not using docs/pages without trouble.
https://github.com/facebook/docusaurus/issues/3360

* fix netlify redirects

* do not throw if useDocs do not load?

* netlify deploy typo

* try to fix useDocs

* docs(v2): update Deploy to Vercel guide (#3344)

* filter annoying useDocs conditional require warning

* netlify deploy preview homepage

* typo

* try to trigger again CLA bot

Co-authored-by: Sam Ko <sam@vercel.com>

.gitignore

@@ -30,6 +30,6 @@ packages/docusaurus-plugin-ideal-image/lib/
 packages/docusaurus-theme-classic/lib/
 packages/docusaurus-migrate/lib/
 
-website/netlifyDeploy
+website/netlifyDeployPreview
 
 website-1.x-migrated

package.json

@@ -14,11 +14,13 @@
     "start:v2:watch": "nodemon --watch \"./packages/*/lib/**/*.*\" --exec \"yarn start:v2\"",
     "start:v2:baseUrl": "yarn workspace docusaurus-2-website start:baseUrl",
     "start:v2:bootstrap": "yarn workspace docusaurus-2-website start:bootstrap",
+    "start:v2:blogOnly": "yarn workspace docusaurus-2-website start:blogOnly",
     "build": "yarn build:packages && yarn build:v2",
     "build:packages": "lerna run build --no-private",
     "build:v1": "yarn workspace docusaurus-1-website build",
     "build:v2": "yarn workspace docusaurus-2-website build",
     "build:v2:baseUrl": "yarn workspace docusaurus-2-website build:baseUrl",
+    "build:v2:blogOnly": "yarn workspace docusaurus-2-website build:blogOnly",
     "serve:v1": "serve website-1.x/build/docusaurus",
     "serve:v2": "serve website/build",
     "serve:v2:baseUrl": "serve website",

packages/docusaurus-preset-bootstrap/src/index.js

@@ -9,9 +9,21 @@ module.exports = function preset(context, opts = {}) {
   return {
     themes: [[require.resolve('@docusaurus/theme-bootstrap'), opts.theme]],
     plugins: [
-      [require.resolve('@docusaurus/plugin-content-pages'), opts.pages],
-      [require.resolve('@docusaurus/plugin-content-blog'), opts.blog],
-      [require.resolve('@docusaurus/plugin-content-docs'), opts.docs],
+      [
+        opts.pages !== false &&
+          require.resolve('@docusaurus/plugin-content-pages'),
+        opts.pages,
+      ],
+      [
+        opts.blog !== false &&
+          require.resolve('@docusaurus/plugin-content-blog'),
+        opts.blog,
+      ],
+      [
+        opts.docs !== false &&
+          require.resolve('@docusaurus/plugin-content-docs'),
+        opts.docs,
+      ],
     ],
   };
 };

packages/docusaurus-preset-classic/src/index.js

@@ -21,15 +21,28 @@ module.exports = function preset(context, opts = {}) {
       algolia && require.resolve('@docusaurus/theme-search-algolia'),
     ],
     plugins: [
-      [require.resolve('@docusaurus/plugin-content-docs'), opts.docs],
-      [require.resolve('@docusaurus/plugin-content-blog'), opts.blog],
-      [require.resolve('@docusaurus/plugin-content-pages'), opts.pages],
+      opts.docs !== false && [
+        require.resolve('@docusaurus/plugin-content-docs'),
+        opts.docs,
+      ],
+      opts.blog !== false && [
+        require.resolve('@docusaurus/plugin-content-blog'),
+        opts.blog,
+      ],
+      opts.pages !== false && [
+        require.resolve('@docusaurus/plugin-content-pages'),
+        opts.pages,
+      ],
       isProd &&
         googleAnalytics &&
         require.resolve('@docusaurus/plugin-google-analytics'),
       debug && require.resolve('@docusaurus/plugin-debug'),
       isProd && gtag && require.resolve('@docusaurus/plugin-google-gtag'),
-      isProd && [require.resolve('@docusaurus/plugin-sitemap'), opts.sitemap],
+      isProd &&
+        opts.sitemap !== false && [
+          require.resolve('@docusaurus/plugin-sitemap'),
+          opts.sitemap,
+        ],
     ],
   };
 };

packages/docusaurus-theme-classic/src/index.js

@@ -95,6 +95,13 @@ module.exports = function (context, options) {
         .join('|');
 
       return {
+        stats: {
+          warningsFilter: [
+            // See https://github.com/facebook/docusaurus/pull/3382
+            (warning) =>
+              warning.includes("Can't resolve '@theme-init/hooks/useDocs"),
+          ],
+        },
         plugins: [
           new ContextReplacementPlugin(
             /prismjs[\\/]components$/,

packages/docusaurus-theme-classic/src/theme/NavbarItem/index.tsx

@@ -6,25 +6,30 @@
  */
 
 import React from 'react';
-import DocsVersionNavbarItem from '@theme/NavbarItem/DocsVersionNavbarItem';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
-import DocsVersionDropdownNavbarItem from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
 import type {Props} from '@theme/NavbarItem';
 
 const NavbarItemComponents = {
-  default: DefaultNavbarItem,
-  docsVersion: DocsVersionNavbarItem,
-  docsVersionDropdown: DocsVersionDropdownNavbarItem,
+  default: () => DefaultNavbarItem,
+
+  // Need to lazy load these items as we don't know for sure the docs plugin is loaded
+  // See https://github.com/facebook/docusaurus/issues/3360
+  docsVersion: () =>
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    require('@theme/NavbarItem/DocsVersionNavbarItem').default,
+  docsVersionDropdown: () =>
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    require('@theme/NavbarItem/DocsVersionDropdownNavbarItem').default,
 } as const;
 
 const getNavbarItemComponent = (
   type: keyof typeof NavbarItemComponents = 'default',
 ) => {
-  const NavbarItemComponent = NavbarItemComponents[type];
-  if (!NavbarItemComponent) {
+  const navbarItemComponent = NavbarItemComponents[type];
+  if (!navbarItemComponent) {
     throw new Error(`No NavbarItem component found for type=${type}.`);
   }
-  return NavbarItemComponent;
+  return navbarItemComponent();
 };
 
 export default function NavbarItem({type, ...props}: Props): JSX.Element {

packages/docusaurus-theme-classic/src/theme/hooks/useDocs.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// See https://github.com/facebook/docusaurus/issues/3360
+// TODO find a better solution, this shouldn't be needed
+
+// TODO this is not ideal and produce a warning!
+// see https://github.com/webpack/webpack/issues/7713#issuecomment-467888437
+// note: warning can be filtered: https://github.com/facebook/docusaurus/pull/3382#issuecomment-684966924
+try {
+  module.exports = require('@theme-init/hooks/useDocs');
+} catch (e) {
+  module.exports = {};
+}
+
+/*
+throw new Error(
+  "The docs plugin is not used, so you can't require the useDocs hooks. ",
+);
+ */

packages/docusaurus/src/server/config.ts

@@ -13,7 +13,11 @@ import {CONFIG_FILE_NAME} from '../constants';
 import {validateConfig} from './configValidation';
 
 export default function loadConfig(siteDir: string): DocusaurusConfig {
-  const configPath = path.resolve(siteDir, CONFIG_FILE_NAME);
+  // TODO temporary undocumented env variable: we should be able to use a cli option instead!
+  const loadedConfigFileName =
+    process.env.DOCUSAURUS_CONFIG || CONFIG_FILE_NAME;
+
+  const configPath = path.resolve(siteDir, loadedConfigFileName);
 
   if (!fs.existsSync(configPath)) {
     throw new Error(`${CONFIG_FILE_NAME} not found`);

packages/docusaurus/src/webpack/utils.ts

@@ -139,6 +139,31 @@ export function applyConfigureWebpack(
   return config;
 }
 
+// See https://webpack.js.org/configuration/stats/#statswarningsfilter
+// @slorber: note sure why we have to re-implement this logic
+// just know that legacy had this only partially implemented, so completed it
+type WarningFilter = string | RegExp | Function;
+function filterWarnings(
+  warningsFilter: WarningFilter[],
+  warnings: string[],
+): string[] {
+  function isWarningFiltered(warning: string): boolean {
+    return warningsFilter.some((warningFilter) => {
+      if (typeof warningFilter === 'string') {
+        return warning.includes(warningFilter);
+      } else if (warningFilter instanceof RegExp) {
+        return !!warning.match(warningFilter);
+      } else if (warningFilter instanceof Function) {
+        return warningFilter(warning);
+      } else {
+        throw new Error(`Unknown warningFilter type = ${typeof warningFilter}`);
+      }
+    });
+  }
+
+  return warnings.filter((warning) => !isWarningFiltered(warning));
+}
+
 export function compile(config: Configuration[]): Promise<void> {
   return new Promise((resolve, reject) => {
     const compiler = webpack(config);
@@ -155,13 +180,12 @@ export function compile(config: Configuration[]): Promise<void> {
       if (stats.hasWarnings()) {
         // Custom filtering warnings (see https://github.com/webpack/webpack/issues/7841).
         let {warnings} = stats.toJson('errors-warnings');
+
         const warningsFilter = ((config[0].stats as Stats.ToJsonOptionsObject)
-          ?.warningsFilter || []) as any[];
+          ?.warningsFilter || []) as WarningFilter[];
 
         if (Array.isArray(warningsFilter)) {
-          warnings = warnings.filter((warning) =>
-            warningsFilter.every((str) => !warning.includes(str)),
-          );
+          warnings = filterWarnings(warningsFilter, warnings);
         }
 
         warnings.forEach((warning) => {

website/docusaurus.config-blog-only.js

@@ -0,0 +1,63 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  title: 'Docusaurus blog only!',
+  tagline: 'Build optimized websites quickly, focus on your content',
+  organizationName: 'facebook',
+  projectName: 'docusaurus',
+  baseUrl: '/blog-only/',
+  url: 'https://v2.docusaurus.io',
+  onBrokenLinks: 'throw',
+  favicon: 'img/docusaurus.ico',
+  themes: ['@docusaurus/theme-live-codeblock'],
+  plugins: [],
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: false,
+        pages: false,
+        blog: {
+          routeBasePath: '/',
+          path: '../website-1.x/blog',
+          editUrl:
+            'https://github.com/facebook/docusaurus/edit/master/website-1.x/',
+          postsPerPage: 3,
+          feedOptions: {
+            type: 'all',
+            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
+          },
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+  themeConfig: {
+    image: 'img/docusaurus-soc.png',
+    navbar: {
+      hideOnScroll: true,
+      title: 'Docusaurus',
+      logo: {
+        alt: 'Docusaurus Logo',
+        src: 'img/docusaurus.svg',
+        srcDark: 'img/docusaurus_keytar.svg',
+      },
+    },
+    footer: {
+      style: 'dark',
+      logo: {
+        alt: 'Facebook Open Source Logo',
+        src: 'img/oss_logo.png',
+        href: 'https://opensource.facebook.com',
+      },
+      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc. Built with Docusaurus.`,
+    },
+  },
+};

website/netlify.toml

@@ -11,11 +11,12 @@
 # permits to test that baseUrl works fine (this often breaks!)
 [context.deploy-preview]
   command = "yarn workspace docusaurus-2-website netlify:build:deployPreview"
-  publish = "website/netlifyDeploy"
+  publish = "website/netlifyDeployPreview"
 
   # TODO this does not seem to work
-  # workaroud: a _redirect file is created in website/netlifyDeploy
+  # workaroud: a _redirect file is created in npm/yarn scripts
   # can't we have context-based redirects with Netlify? :'(
+
   [[context.deploy-preview.redirects]]
     from = "/classic/*"
     to = "/classic/404.html"
@@ -24,6 +25,10 @@
     from = "/bootstrap/*"
     to = "/bootstrap/404.html"
     status = 200
+  [[context.deploy-preview.redirects]]
+    from = "/blog-only/*"
+    to = "/blog-only/404.html"
+    status = 200
   [[context.deploy-preview.redirects]]
     from = "/*"
     to = "/classic/"

website/netlifyDeployPreview/_redirects

@@ -0,0 +1,4 @@
+/classic/* /classic/404.html 200
+/bootstrap/* /bootstrap/404.html 200
+/blog-only/* /blog-only/404.html 200
+/* /classic/

website/netlifyDeployPreview/index.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+  <body style="padding: 20px;">
+    <img src="https://v2.docusaurus.io/img/docusaurus.png" />
+    <h1 style="margin-top: 20px;">
+      Docusaurus deploy previews
+    </h1>
+    <section style="margin-top: 40px;">
+      <p>
+        We deploy the Docusaurus site with various configurations. It helps us
+        find potential regressions.
+      </p>
+      <p>When in doubt, try the <a href="/classic">classic preview</a></p>
+    </section>
+    <section style="margin-top: 40px;">
+      <h2>Available deploy previews:</h2>
+      <ul style="margin-top: 20px;">
+        <li style="margin-top: 20px;">
+          <a href="/classic">classic</a>: the regular site
+        </li>
+        <li style="margin-top: 20px;">
+          <a href="/bootstrap">bootstrap</a>: the regular site with the
+          bootstrap theme (WIP)
+        </li>
+        <li style="margin-top: 20px;">
+          <a href="/blog-only">blog-only</a>: the regular site in blog-only mode
+        </li>
+      </ul>
+    </section>
+  </body>
+</html>

website/package.json

@@ -12,11 +12,13 @@
     "build:baseUrl": "BASE_URL='/build/' yarn build",
     "start:bootstrap": "DOCUSAURUS_PRESET=bootstrap yarn start",
     "build:bootstrap": "DOCUSAURUS_PRESET=bootstrap yarn build",
+    "start:blogOnly": "DOCUSAURUS_CONFIG='docusaurus.config-blog-only.js' yarn start",
+    "build:blogOnly": "DOCUSAURUS_CONFIG='docusaurus.config-blog-only.js' yarn build",
     "netlify:build:production": "yarn build",
-    "netlify:build:deployPreview": "yarn rimraf netlifyDeploy && yarn netlify:build:deployPreview:classic && yarn netlify:build:deployPreview:bootstrap && yarn netlify:build:deployPreview:redirects",
-    "netlify:build:deployPreview:classic": "BASE_URL='/classic/' yarn build --out-dir netlifyDeploy/classic",
-    "netlify:build:deployPreview:bootstrap": "BASE_URL='/bootstrap/' DOCUSAURUS_PRESET=bootstrap DISABLE_VERSIONING=true yarn build --out-dir netlifyDeploy/bootstrap",
-    "netlify:build:deployPreview:redirects": "echo 'Writing Netlify baseUrl deployPreview _redirects file' && echo '/classic/* /classic/404.html 200' >> netlifyDeploy/_redirects && echo '/bootstrap/* /bootstrap/404.html 200' >> netlifyDeploy/_redirects && echo '/* /classic/' >> netlifyDeploy/_redirects",
+    "netlify:build:deployPreview": "yarn netlify:build:deployPreview:classic && yarn netlify:build:deployPreview:bootstrap && yarn netlify:build:deployPreview:blogOnly",
+    "netlify:build:deployPreview:classic": "BASE_URL='/classic/' yarn build --out-dir netlifyDeployPreview/classic",
+    "netlify:build:deployPreview:bootstrap": "BASE_URL='/bootstrap/' DOCUSAURUS_PRESET=bootstrap DISABLE_VERSIONING=true yarn build --out-dir netlifyDeployPreview/bootstrap",
+    "netlify:build:deployPreview:blogOnly": "yarn build:blogOnly --out-dir netlifyDeployPreview/blog-only",
     "netlify:test": "yarn netlify:build:deployPreview && yarn netlify dev --debug"
   },
   "dependencies": {