I’m using Facebook’s open source tool Docusaurus to provide documentation for a software component I’m currently developing. So far everything has been working great, but now requirements are getting a little more complicated and I’m struggling to achieve the desired state for the docs. So here’s the scenario that I would like to set up:
- After initial
1.0release a1.1is coming up soon (and more versions in the future of course), so I need to introduce versioning (accompanied by a dropdown in the navbar to conveniently switch between versions). ✅ - The software component documented is available for both Android and iOS and pretty soon versions will start to diverge, so I will need to have two dedicated structures instead of just one, that can be versioned independently (so actually multiple versioning dropdowns in navbar, one for each supported platform). ✅
- Besides that, there are a few documents, that are “valid” for all versions, like a changelog or licensing terms. So there should be a section with unversioned “global” files. ✅
- Last but not least – and that seems to be the tricky thing – all of these parts of the documentation should share one single sidebar, giving you access to both versioned and unversioned content. ❌
Of course I studied the Docusaurus documentation extensively and already played around a lot with the different possibilities described there. Basically requirements #1-3 I was able to set up, even combinations of them. It’s the last one, requirement #4, that I’m having trouble with. So far I couldn’t manage to get one common sidebar for all of this. As you can see, my scenario is remarkably close to the one described in the examples, but that last step above is not sufficiently explained (or I’m missing something here or it’s not possible at all…).
By now, I have a file structure like this:
./ (Docusaurus root)
├ android/ (Android-specific content, versioned, default docs dir)
│ ├ initialization.md
│ ├ authentication.md
│ └ configuration.md
├ ios/ (iOS-specific content, versioned, via plugin-content-docs)
│ ├ initialization.md
│ ├ authentication.md
│ └ configuration.md
├ common/ (“global” content, unversioned, via plugin-content-docs)
│ ├ changelog.md
│ └ license.md
├ versioned_docs/ (Android-specific “past versions” content)
│ └ version-1.0
│ ├ initialization.md
│ ├ authentication.md
│ └ configuration.md
├ versioned_sidebars/ (Android-specific “past versions” sidebars)
│ └ version-1.0-sidebars.json
├ ios_versioned_docs/ (iOS-specific “past versions” content)
│ ├ version-1.0
│ │ ├ initialization.md
│ │ ├ authentication.md
│ │ └ configuration.md
│ └ version-1.1
│ ├ initialization.md
│ ├ authentication.md
│ └ configuration.md
├ ios_versioned_sidebars/ (iOS-specific “past versions” sidebars)
│ ├ version-1.0-sidebars.json
│ └ version-1.1-sidebars.json
├ sidebars.js
├ ios_sidebars.js
├ common_sidebars.js
├ versions.json
├ ios_versions.json
├ docusaurus.config.js
└ … (other files irrelevant for this issue)
… which should map to a simple unified sidebar like this:
Android
Initialization
Authentication
Configuration
iOS
Initialization
Authentication
Configuration
Common
Changelog
License
It is supposed to stay like this, no matter which page I’m on (with the usual proper category folding, active link highlighting etc. of course). The crucial aspect for me is now finding out, what the sidebar(s) portion of the code must look like. Based on the given example the relevant part of my docusaurus.config.js could be close to this:
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
path: 'android',
routeBasePath: 'android',
sidebarPath: require.resolve('./sidebars.js')
},
},
],
],
plugins: [
[
'@docusaurus/plugin-content-docs',
{
id: 'ios',
path: 'ios',
routeBasePath: 'ios',
sidebarPath: require.resolve('./ios_sidebars.js')
},
],
[
'@docusaurus/plugin-content-docs',
{
id: 'common',
path: 'common',
routeBasePath: 'common',
sidebarPath: require.resolve('./common_sidebars.js')
}
]
]
};
But that unfortunately doesn’t do it and I’m unsure about the correct content of these referenced sidebar definition files, because it is never shown in the example. Here’s what I’ve tried so far (after consulting sidebar-specific docs and other resources):
- Fill each of the three sidebar files with an
{ type: autogenerated, dirName: '.' }item (surronding code left out for brevity), hoping there was some magic working in the background. That just resulted in the Android-specific sidebar being shown (or other ones instead, depending in which category I manually navigated by adjusting the URL). - Adjust the
dirNamevalues to'ios'and'common'respectively, because'.'points to the default docs dir (orandroiddir in my case). That resulted in an error saying, that I needed to define the dirs relative to the default docs dir. - Define the
dirNamevalues relative to the default docs dir with'../ios'/'../common', which resulted in an error:No docs found in "../ios": can't auto-generate a sidebar. - Put
iosandcommonfolder and their content in theandroidfolder, so I can just use'ios'and'common'as relativedirNamevalues …but that obviously doesn’t make sense, because it messes up the hierarchy and suddenly includes thecommonfolder during versioning. - Experiment with just one single
sidebars.jsfile in various combinations, which always led to one of the above situations.
So as you can see I already tried a lot and am running out of ideas. Also I wasn’t able to find any articles, post, or other resources describing my exact scenario, although I would’ve that it should be rather common. One Stack Overflow thread came close, but it doesn’t include the versioning scenario and also doesn’t show the actually relevant sidebar portion of the code. Any help would be very much appreciated!
