Sidebar.js Doesn't Gracefully Ignore Unknown Props

[justinryder]

🐛 Bug Report

If you add an unknown prop to an otherwise valid saidebars.js, instead of gracefully ignoring the props, the build fails.

Reasoning/Issue This Causes Us

We are using Docusaurus within an Nx monorepo and we want to create a schematic that will auto generate a new docs page and update the sidebar. To do this, we will need to programatically identify which category to add the new docs page into, but without a key, we'd need to rely on the user-facing label. Adding a key property to the sidebar categories would allow us to do that easily, but that breaks Docusaurus.

Our sidebars.js structure:

module.exports = {
  docs: [
    { // we need to add a unique key here
      type: "category",
      label: "Library 1",
      items: [
        'library-1/getting_started',
        {
          type: "category",
          label: "Components",
          items: [ // so we know which of these items arrays to insert the new docs reference in
            "library-1/components/component-1",
            "library-1/components/component-2"
          ]
        }
      ],
    },
};

We plan on adding more categories for libraries, hooks, etc as we go so being able to uniquely identify each category at any level of the sidebar tree without relying on the user-friendly label would be very helpful.

To Reproduce

1. Create a docs site with a valid sidebars.js using the category objects format
2. Add an undocumented property to one of these category objects (e.g. key)

Expected behavior

The docs should still compile, gracefully ignoring the unknown prop.

Actual Behavior

The docs error, breaking the build.

Error message:

Error: Unknown sidebar item keys: key. Item: {"key":"docusaurus","type":"category","label":"Docusaurus","items":["doc1","doc2","doc3"]}
    at assertItem (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\sidebars.js:42:15)
    at assertIsCategory (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\sidebars.js:46:5)
    at normalizeItem (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\sidebars.js:91:13)
    at arrayMap (C:\Git\Personal\docusaurus\examples\facebook\node_modules\lodash.flatmap\index.js:140:21)
    at map (C:\Git\Personal\docusaurus\examples\facebook\node_modules\lodash.flatmap\index.js:1928:10)
    at Object.flatMap [as default] (C:\Git\Personal\docusaurus\examples\facebook\node_modules\lodash.flatmap\index.js:1881:22)
    at normalizeSidebar (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\sidebars.js:114:36)
    at C:\Git\Personal\docusaurus\examples\facebook\node_modules\lodash\lodash.js:13427:38
    at C:\Git\Personal\docusaurus\examples\facebook\node_modules\lodash\lodash.js:4925:15
    at baseForOwn (C:\Git\Personal\docusaurus\examples\facebook\node_modules\lodash\lodash.js:2990:24)
    at Function.mapValues (C:\Git\Personal\docusaurus\examples\facebook\node_modules\lodash\lodash.js:13426:7)
    at normalizeSidebars (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\sidebars.js:117:21)
    at Object.loadSidebars (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\sidebars.js:132:12)
    at loadVersion (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\index.js:95:45)
    at Array.map (<anonymous>)
    at Object.loadContent (C:\Git\Personal\docusaurus\examples\facebook\node_modules\@docusaurus\plugin-content-docs\lib\index.js:147:68)

Your Environment

• Docusaurus version used: v2.0.0-alpha.68
• Environment name and version: Node v12.18.3, Yarn v1.22.4
• Operating system and version: Windows 10 Enterprise v10.0.18363 Build 18363

Reproducible Demo

I forked the repo and updated the facebook example to use the categories format to show that works:
https://github.com/justinryder/docusaurus/blob/sidebar-category-working-example/examples/facebook/sidebars.js

Then I updated that working example to add an unknown key to show the bug:
https://github.com/justinryder/docusaurus/blob/sidebar-category-bug-example/examples/facebook/sidebars.js

[slorber]

Hi,

Not totally sure to understand what you are trying to do, but you can write your sidebar in any format you want. What matters is that you feed Docusaurus with the correct json format, but you can write your sidebar in yaml and transform it to json with js code if you want to.

We forbid unknown keys. because we want to fail-fast, avoid bad configs, typos etc... it's more a feature than a bug.

If you want to add a key to your custom sidebar config format, you can, but you'll have to strip those keys.

module.exports = removeKeys(myCustomJsonSidebarFormat)

If that helps, here's a generic fn we have to transform sidebars:

export function transformSidebarItems(
  sidebar: Sidebar,
  updateFn: (item: SidebarItem) => SidebarItem,
): Sidebar {
  function transformRecursive(item: SidebarItem): SidebarItem {
    if (item.type === 'category') {
      return updateFn({
        ...item,
        items: item.items.map(updateFn),
      });
    }
    return updateFn(item);
  }
  return sidebar.map(transformRecursive);
}

[justinryder]

Not totally sure to understand what you are trying to do

We're trying to programatically update the sidebars.js when adding a new docs page, since this will be done via an Nx schematic.

e.g.

> nx workspace-schematic create-doc
Library name:
> library-1
Component name:
> Component3

would run the create doc schematic, adding a component-3.md file with a template docs page and update sidebars.js to reference component-3 in the relevant category based on which library was specified.

I suppose based on the info you provided, our best bet would be to have a separate "source of truth" (sidebars.schema.js or something like that) that includes the additional meta data we need to programatically transform it when adding a new doc, then as a second step after adding a new doc to the tree, we would convert that source of truth file into the actual sidebars.js, adhering to the Docusaurus structure.

Thank you for the info! :)

[slorber]

yes that's it

you could do

import myCustomSidebar from "myCustomSidebar.json"

export default removeKeys(myCustomSidebar);

Quite related to this other issues where users would like to auto generate the sidebar according to the FS structure, with some potential userland solutions: #3464

Important note: when versioning docs, we snapshot using the docusaurus sidebar format as json, we don't run your custom code on versioned docs anymore (but some users were interested by this option here #3285 (comment))

[slorber]

FYI we may allow passing arbitrary attributes, as it can also be useful when you want to customize the theme (ie the theme should receive the attributes too).

Let's track it here: #3787