Sidebar generator

README.md

@@ -3,7 +3,9 @@
 This website is built using [Docusaurus 2](https://docusaurus.io/), a modern
 static website generator.
 
-## Docs Sourcer
+## Overview
+
+### Docs Sourcer
 
 All of the content that we see on the docs site is rendered to the top level
 `docs/` folder by the
@@ -16,15 +18,15 @@ pull in tagged content from other files, located in other GitHub repos, pull in
 images and auto-correct links. This will allow content creators to have more
 features when authoring content.
 
-## Content creation
+### Content creation
 
 All manually created MarkDown source content lives in the `_docs-sources/`
 folder. The top level `docs/` folder contains the _generated_ output that
 results after the `docs-sourcer` processes the `_docs-sources/` directory.
 Grunts should **never edit any of the MarkDown files in the `docs/` folder
 directly**. We should always be editing the content in `_docs-sources/`.
 
-## Installation of dependencies
+## Installing dependencies
 
 ```sh
 yarn
@@ -43,16 +45,7 @@ you edit a file in `_docs-sources/` then the `docs-sourcer` will automatically
 re-run to regenerate the output files. Docusaurus will then hot-reload that
 content so that to the end user, they have "live reloading" while authoring.
 
-### Run production build locally
-
-```sh
-yarn build && yarn serve
-```
-
-This will create and serve a production build. This can be used to verify the
-expected behaviors in a production environment and view the Google analytics.
-
-## Committing changes to docs
+### Committing changes
 
 While authoring local content, you will exclusively be making your changes in
 the `_docs-sources/` folder. The `docs-sourcer` will then pre-process and
@@ -64,7 +57,16 @@ Generated content should be up to date if you are previewing locally while
 editing but you may wish to manually regenerate the output (see section below)
 to ensure it is totally up to date.
 
-## Manually generating docs output
+### Running a production build locally
+
+```sh
+yarn build && yarn serve
+```
+
+This will create and serve a production build. This can be used to verify the
+expected behaviors in a production environment and view the Google analytics.
+
+### Manually generating docs output
 
 It's possible to manually regenerate output content from the sources in
 `_docs-sources/`:
@@ -76,11 +78,28 @@ yarn regenerate:local
 This command can be run at any time, regardless of whether `yarn start` is
 currently running.
 
-## Build
+### Generating sidebars for guides
+
+We utilitize explicit sidebar definitions for most of our docs content. Doing
+so enables authors to easily provide explicit titles for all category labels,
+as well as define the relative ordering of pages in a maintainable way.
+Long-form docs with many sections receive a dedicated sidebar to provide a
+focused reading experience (e.g. /guides/build-it-yourself/\*).
+
+A tool is provided to automatically generate sidebars for any new guide. To
+run it, specify the path to the directory you wish to create a sidebar for in
+either `_docs-sources/` or the output `docs/` path, relative to your current
+working directory.
 
 ```sh
-yarn build
+yarn sidebar docs/guides/build-it-yourself/my-new-guide/
 ```
 
-This command generates static content into the `build` directory and can be
-served using any static contents hosting service.
+Once generated, you're free to adjust the names of each category, which only
+appear in the sidebar itself. You may also reorder any of the linked pages
+within each section, which will be reflected in the rendered output.
+
+See the usage instructions with `yarn sidebar --help` to learn how to add a
+back button or specify an output file. The resulting file should be placed in
+the `sidebars/` directory. You'll also need to require this file in
+`sidebars.js`, and then re-run `yarn start` to see your changes.

jest.config.js

@@ -0,0 +1,12 @@
+/*
+ * For a detailed explanation regarding each configuration property, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+module.exports = {
+  clearMocks: true,
+  collectCoverage: true,
+  coverageDirectory: "coverage",
+  coverageProvider: "v8",
+  preset: "ts-jest",
+}

package.json

@@ -14,13 +14,16 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
     "regenerate": "env-cmd --silent docs-sourcer",
-    "regenerate:local": "yarn regenerate --plugins local-copier"
+    "regenerate:local": "yarn regenerate --plugins local-copier",
+    "sidebar": "scripts/generate-sidebar.js",
+    "test": "jest"
   },
   "dependencies": {
     "@docusaurus/core": "^2.0.0-beta.14",
     "@docusaurus/preset-classic": "^2.0.0-beta.14",
     "@mdx-js/react": "^1.6.21",
     "@svgr/webpack": "^5.5.0",
+    "@types/jest": "^27.4.0",
     "clsx": "^1.1.1",
     "config": "^3.3.6",
     "env-cmd": "^10.1.0",
@@ -32,11 +35,13 @@
     "react": "^17.0.1",
     "react-dom": "^17.0.1",
     "react-modal": "^3.14.4",
+    "ts-jest": "^27.1.3",
     "url-loader": "^4.1.1"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "^2.0.0-beta.14",
     "@tsconfig/docusaurus": "^1.0.4",
+    "jest": "^27.4.7",
     "onchange": "^7.1.0",
     "typescript": "^4.3.5"
   },

scripts/generate-sidebar.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const yargs = require("yargs/yargs")
+const path = require("path")
+const fs = require("fs")
+const {
+  generateSidebarFile,
+  generateMultiSidebarFile,
+} = require("./sidebar-lib")
+
+// when running with yarn, we need to prepend the initial
+// working directory to the path
+const resolveDir = (dir) => {
+  if (process.env.INIT_CWD) {
+    return path.resolve(path.join(process.env.INIT_CWD, dir))
+  } else {
+    return path.resolve(dir)
+  }
+}
+
+async function main() {
+  const { hideBin } = require("yargs/helpers")
+
+  // parse command line args
+  const argv = yargs(hideBin(process.argv))
+    .usage("$0 [-bv] [-o file] [directory]")
+    .option("back", {
+      alias: "b",
+      type: "string",
+      description: "Include a back button with the specified label",
+    })
+    .option("output", {
+      alias: "o",
+      type: "string",
+      description: "The path at which to write sidebar file",
+    })
+    .option("verbose", {
+      alias: "v",
+      type: "boolean",
+      description: "Run with verbose logging",
+    })
+    .positional("directory", {
+      description:
+        "The directory to generate a sidebar for, e.g. a multi-page guide, or a list of directories to generate a multi-sidebar file",
+    })
+    .strictOptions()
+    .version("1.0")
+    .parse()
+
+  const opts = {
+    backButton: argv.back,
+    verbose: argv.verbose,
+  }
+
+  let data
+
+  // generate a single or multi-sidebar file
+  try {
+    if (argv._.length < 2) {
+      // operate on the working dir if not otherwise specified
+      const inputDir = resolveDir(argv._[0] || ".")
+      data = await generateSidebarFile(inputDir, opts)
+    } else {
+      const inputDirs = argv._.map(resolveDir)
+      data = await generateMultiSidebarFile(inputDirs, opts)
+    }
+  } catch (err) {
+    console.log(`ERROR: Failed to generate a sidebar — %o`, err.message)
+    process.exit(1)
+  }
+
+  if (opts.verbose) {
+    console.log(
+      "Done. Don't forget to place your sidebar file in /sidebars and update /sidebars.js to require it.\n"
+    )
+  }
+
+  // write to file or print to stdout
+  if (argv.output) {
+    fs.writeFile(argv.output, data, (err) => {
+      if (err) {
+        console.log("Error writing sidebar file: ", err)
+      } else {
+        console.log("Wrote sidebar file to %o", argv.output)
+      }
+    })
+  } else {
+    console.log(data)
+  }
+}
+
+main()