feat(v2): postBuild() - plugin lifecycle (#1302)

* feat(v2): build() - plugin lifecycle

* rename to postBuild

packages/docusaurus-plugin-sitemap/__tests__/index.test.js

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import loadSetup from '../../docusaurus/test/loadSetup';
+import DocusaurusPluginSitemap from '../index';
+
+describe('docusaurus-plugin-sitemap', () => {
+  describe('createSitemap', () => {
+    test.each(['simple', 'versioned', 'translated', 'transversioned'])(
+      '%s website',
+      async type => {
+        const props = await loadSetup(type);
+        const plugin = new DocusaurusPluginSitemap(null, props);
+        const sitemap = await plugin.createSitemap(props);
+        expect(sitemap).toContain(
+          `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">`,
+        );
+      },
+    );
+
+    test('empty site', async () => {
+      const props = await loadSetup('empty');
+      const plugin = new DocusaurusPluginSitemap(null, props);
+      expect(
+        plugin.createSitemap(props),
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"Url in docusaurus.config.js cannot be empty/undefined"`,
+      );
+    });
+  });
+});

packages/docusaurus-plugin-sitemap/index.js

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const fs = require('fs');
+const sitemap = require('sitemap');
+const path = require('path');
+
+const DEFAULT_OPTIONS = {
+  cacheTime: 600 * 1000, // 600 sec - cache purge period
+  changefreq: 'weekly',
+  priority: 0.5,
+};
+
+class DocusaurusPluginSitemap {
+  constructor(opts, context) {
+    this.options = {...DEFAULT_OPTIONS, ...opts};
+    this.context = context;
+  }
+
+  getName() {
+    return 'docusaurus-plugin-sitemap';
+  }
+
+  async createSitemap({siteConfig = {}, routesPaths}) {
+    const {url: hostname} = siteConfig;
+    if (!hostname) {
+      throw new Error(`Url in docusaurus.config.js cannot be empty/undefined`);
+    }
+
+    const urls = routesPaths.map(routesPath => ({
+      url: routesPath,
+      changefreq: this.changefreq,
+      priority: this.priority,
+    }));
+
+    return sitemap
+      .createSitemap({
+        hostname,
+        cacheTime: this.cacheTime,
+        urls,
+      })
+      .toString();
+  }
+
+  async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
+    // Generate sitemap
+    const generatedSitemap = await this.createSitemap({
+      siteConfig,
+      routesPaths,
+    });
+
+    // Write sitemap file
+    const sitemapPath = path.join(outDir, 'sitemap.xml');
+    return fs.writeFile(sitemapPath, generatedSitemap);
+  }
+}
+
+module.exports = DocusaurusPluginSitemap;

packages/docusaurus-plugin-sitemap/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@docusaurus/plugin-sitemap",
+  "version": "1.0.0",
+  "description": "Simple sitemap generation plugin for Docusaurus",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "sitemap": "^2.1.0"
+  }
+}

packages/docusaurus/lib/commands/build.js

@@ -12,7 +12,6 @@ const chalk = require('chalk');
 const fs = require('fs-extra');
 const globby = require('globby');
 const load = require('../load');
-const createSitemap = require('../core/sitemap');
 const createServerConfig = require('../webpack/server');
 const createClientConfig = require('../webpack/client');
 const {applyConfigureWebpack} = require('../webpack/utils');
@@ -86,10 +85,15 @@ module.exports = async function build(siteDir) {
     }),
   );
 
-  // Generate sitemap.
+  /* Plugin lifecycle - postBuild */
-  const sitemap = await createSitemap(props);
+  await Promise.all(
-  const sitemapPath = path.join(outDir, 'sitemap.xml');
+    plugins.map(async plugin => {
-  await fs.writeFile(sitemapPath, sitemap);
+      if (!plugin.postBuild) {
+        return;
+      }
+      await plugin.postBuild(props);
+    }),
+  );
 
   const relativeDir = path.relative(process.cwd(), outDir);
   console.log(

packages/docusaurus/lib/core/sitemap.js

@@ -1,36 +0,0 @@
-/**
- * Copyright (c) 2017-present, Facebook, Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-const sitemap = require('sitemap');
-const loadConfig = require('../load/config');
-
-module.exports = async function createSitemap({
-  siteConfig = {},
-  routesPaths = [],
-}) {
-  const {url: siteUrl} = siteConfig;
-
-  if (!siteUrl) {
-    throw new Error(
-      `Url in ${loadConfig.configFileName} cannot be empty/undefined`,
-    );
-  }
-
-  const urls = routesPaths.map(routesPath => ({
-    url: routesPath,
-    changefreq: 'weekly',
-    priority: 0.5,
-  }));
-
-  const generatedSitemap = sitemap.createSitemap({
-    hostname: siteUrl,
-    cacheTime: 600 * 1000, // 600 sec - cache purge period
-    urls,
-  });
-
-  return generatedSitemap.toString();
-};

packages/docusaurus/package.json

@@ -62,7 +62,6 @@
     "react-router-dom": "^4.3.1",
     "semver": "^5.5.0",
     "shelljs": "^0.8.2",
-    "sitemap": "^2.1.0",
     "static-site-generator-webpack-plugin": "^3.4.2",
     "style-loader": "^0.22.1",
     "terser-webpack-plugin": "^1.1.0",

packages/docusaurus/plugins/README.md

@@ -70,14 +70,39 @@ class DocusaurusPlugin {
   }
 
   async contentLoaded({content, actions}) {
-    // loaded hook is done after load hook is done
+    // contentLoaded hook is done after loadContent hook is done
     // actions are set of functional API provided by Docusaurus. e.g: addRoute
   }
 
+  async postBuild(props) {
+    // after docusaurus <build> finish
+  }
+
+  // TODO
+  async postStart(props) {
+    // docusaurus <start> finish
+  }
+
+  // TODO
+  afterDevServer(app, server) {
+    // https://webpack.js.org/configuration/dev-server/#devserverbefore
+  }
+
+  // TODO
+  beforeDevServer(app, server) {
+    // https://webpack.js.org/configuration/dev-server/#devserverafter
+
+  }
+
   configureWebpack(config, isServer) {
     // Modify internal webpack config. If returned value is an Object, it will be merged into the final config using webpack-merge; If returned value is a function, it will receive the config as the 1st argument and an isServer flag as the 2nd argument.
   }
 
+  // TODO
+  chainWebpack(config, isServer) {
+    // Modify internal webpack config with webpack-chain API
+  }
+
   getPathsToWatch() {
     // path to watch
   }

packages/docusaurus/test/core/sitemap.test.js

@@ -1,51 +0,0 @@
-/**
- * Copyright (c) 2017-present, Facebook, Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-import '@babel/polyfill';
-import createSitemap from '@lib/core/sitemap';
-import loadSetup from '../loadSetup';
-
-describe('sitemap', () => {
-  test('simple site', async () => {
-    const props = await loadSetup('simple');
-    const sitemap = await createSitemap(props);
-    expect(sitemap).toContain(
-      `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">`,
-    );
-  });
-
-  test('translated site', async () => {
-    const props = await loadSetup('translated');
-    const sitemap = await createSitemap(props);
-    expect(sitemap).toContain(
-      `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">`,
-    );
-  });
-
-  test('versioned site', async () => {
-    const props = await loadSetup('versioned');
-    const sitemap = await createSitemap(props);
-    expect(sitemap).toContain(
-      `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">`,
-    );
-  });
-
-  test('translated + versioned site', async () => {
-    const props = await loadSetup('transversioned');
-    const sitemap = await createSitemap(props);
-    expect(sitemap).toContain(
-      `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">`,
-    );
-  });
-
-  test('empty site', async () => {
-    const props = await loadSetup('empty');
-    expect(createSitemap(props)).rejects.toThrowErrorMatchingInlineSnapshot(
-      `"Url in docusaurus.config.js cannot be empty/undefined"`,
-    );
-  });
-});

website/docusaurus.config.js

@@ -40,5 +40,8 @@ module.exports = {
     {
       name: '@docusaurus/plugin-content-pages',
     },
+    {
+      name: '@docusaurus/plugin-sitemap',
+    },
   ],
 };