Docusaurus: Allow using one doc id in multiple sidebars

[SleepWalker]

🚀 Feature

Allow the same document to be specified in multiple sidebars.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

Improve navigation across the docs

Currently we have a limitation. A document can be child of only one sidebar, which has a bad impact on navigation in case, when you have one sidebar containing "high level" TOC and multiple sidebars with some docs regarding "low level" details for corresponding high level doc.

For example you have the following sidebar.json:

{
  "docs": {
    "Guides": [
      "adding-blog",
      "custom-pages",
      "search",
      "navigation",
      "translation",
      "versioning"
    ]
  },
  "blog": {
    "General": [
      "adding-comments",
      "setup-author",
      "post-sharing",
      "blog-rss"
    ]
  }
}

To make the main sidebar shorter, we splitting more specific docs into a separate section with it's own sidebar. In this example document adding-blog links to more specific docs, like adding-comments. It would be great to have a link to adding-blog in "blog" sidebar to let the user return back to the "docs" sidebar and high-level article.

Pitch

The reason why we can not have one document in multiple sidebars (as far as I know) is because we need a way to decide which sidebar to show for document, that is in multiple sidebars.

To solve this problem I propose to use dot notation. E.g.:

{
  "docs": {
    "Guides": [
      "adding-blog",
      "..."
    ]
  },
  "blog": {
    "General": [
      "docs.adding-blog",
      "adding-comments",
      "..."
    ]
  }
}

This way we will know, that adding-blog should have "docs" sidebar, but at the same time "blog" sidebar will link to adding-blog too.

Alternatively we can use some prefix e.g. link:, to show, that this sidebar only links to that doc. This prefix can be extended to allow absolute links too, e.g. link:/storybook or link:https://external-docs.com.

And the most universal variant is to use objects instead of strings to allow for more precise and flexible configuration.

[SleepWalker]

In case when this issue will be accepted, I can add support for custom links from #827

[endiliey]

@SleepWalker

Are you planning to work on all of this or just the custom links support from #827 ?

[SleepWalker]

I would like to work on all of this. I think, that two issues can be solved in one pull request, because it is, actually the same part of the code.

But we need to decide with config structure first.

[endiliey]

@SleepWalker

I think this is a great addition. I have one question though, why do we need a ... notation. Can't it be

{
  "docs": {
    "Guides": [
      "adding-blog"
    ]
  },
  "blog": {
    "General": [
      "docs.adding-blog",
      "adding-comments"
    ]
  }
}

[SleepWalker]

that three dots was just three dots to indicate some "other" config entries. I've wrapped it in quotes so that it will be syntactically correct :)

[endiliey]

My bad, kinda missed that. Maybe next time it should be written as // ...😁.

Anyway, I agree with the dot notation (e.g: docs.adding-blog). The idea of namespacing is great.

I think you can proceed as I think this won't break anything and will be an added feature.

[SleepWalker]

ok.

What will we use for custom links from #827?

[
  "href:/foo/bar", // or `link`, or `url`?
]

or

[
  { // the same format as in siteConfig.js
    "href": "https://github.com",
    "label": "Github"
  }
]

The first one is shorter. The last one is the most flexible. We can also support doc field there.

I think, that there will be very few cases, when the user will need to link to some external resources from sidebar, so we can stick with the last example, because it is the most generic. In future it will possible to add shortcut syntax too.

[endiliey]

Lets go with the last one. Shouldn't be too hard to change it if needed. 👍

[SleepWalker]

@endiliey can I split the code from server/readMetadata.js into several js files to be able to cover them with tests or should I make a separate PR with refactoring only? Current code looks to me a little bit complicated to modify it without any tests written.

[endiliey]

@sleepWalker sure, you can refactor it to many files or maybe smaller functions instead of many files as long as it doesnt change functionality. Tests are great.

If there isnt too much refactor, a separate PR might not be needed.

[SleepWalker]

@endiliey, @ericnakagawa I have a question about next/prev links at the page bottom in case, when we are using Object with href and label to define the sidebar link. In this case the link may point outside current site.

Should the next/prev navigation include this link or should we skip the link and point to the document next (or previous) to the link?

[endiliey]

Cc @joelmarcey @yangshun

[JoelMarcey]

@SleepWalker Hi 👋 Can you provide an example where you may have an external link from an internal doc page?

That said, if that was to happen, I believe either:

1. Link to the external site, but open in a new tab.
2. Link to the next available internal doc

I think we should, at the very least, avoid closing the current site all together.

[SleepWalker]

@JoelMarcey That's a request from #827. It can be that the link will point to the same domain, but that may be a page outside of Docusaurus context (e.g. auto-generated API docs with their own layout and navigation).

So which of the two options are better? The second one looks better to me

[JoelMarcey]

@SleepWalker Thanks for the context.

Yeah, I am ok with option 2.

[SleepWalker]

re-claimed :)

[yangshun]

@SleepWalker it's yours!

I've added an "issue: claimed" label so that others will know not to start work on the issue. If you change your mind about the issue, no worries! Just let me know so that I can remove the label and free it up for someone else to claim.

I'll check in with you periodically so that we can keep the task updated with the progress.

[endiliey]

1812