Support versioning of individual sections

[aeneasr]

🚀 Feature

First of all, thank you for docusaurus - we use it exclusively in v1 for https://www.ory.sh/docs/ and it's been a treat!

Similar to Angular, React, and other ecosystems we have several projects (ORY Kratos, ORY Hydra, ...) that need documentation. Right now, we run one docusaurus installation for all these projects. This is very tricky from a versioning standpoint because it is not possible to select a specific version for one project.

For example, one project may be in v1.4.2 and another one may be in v0.3.2. It would be awesome if it was possible to version a section. I've created a small mock up using Docusaurus 1.0:

I'd be happy if there was some way to get this done with docusaurus. Maybe by using the new templating system (I haven't checked it out yet though!). If this is too much work / too breaking
I am also happy for pointers on how to achieve this using another way. Thank you!

Have you read the Contributing Guidelines on issues?

yes

Motivation & Motivation

I think this was covered in the first section, if not please let me know!

[fanny]

I think that would be a good addition, but I don't see many use cases for this feature, because if we have different projects why not create a specific documentation for each?

Right now, as far as I know, we can select an specific version for whole site and see a tag in each page like below:

I think for implement this, we need to change our version system, current we have /docs/versioned_docs and the markdown files, probably we'll need to implement something like versioned_docs/<project_name>/<version>/*.md and in the docs common folder docs/<project_name>

[aeneasr]

I think that would be a good addition, but I don't see many use cases for this feature, because if we have different projects why not create a specific documentation for each?

Yeah, I'm currently exploring to structure them individually (so one docusaurus "installation" per docs) and then just link between the projects. I also think that this would probably be a very edge case solution, especially - as I'm thinking about this - properly tagging / versioning each project will become kind of messy when automated.

Separating docs into different repos for each project probably makes more sense then trying to brute force this feature here.

[DaHolt]

I'd love it if this was possible. At the moment we're having to use four separate docs for each of our products due to each have different versions which is fine, but each one is a separate domain which isn't great. It would be really nice if we could do what we have the moment in one doc and therefore, all docs under one domain.

[yangshun]

Ideally want to have versioning on a sidebar/docs-level, and not on a site-level. That was our oversight when we implemented versioning in v2.

[slorber]

Hey,

This is not properly documented (as there might be upcoming breaking changes in the config) but we can now have multiple instances of the doc plugin running on the same site.

We dogfood this feature on Docusaurus website itself:

• Docs (versioned doc instance): https://v2.docusaurus.io/docs
• Community (unversioned doc instance): https://v2.docusaurus.io/community/support

We don't need to version community, but this multi-docs-instance would permit to manage for example different versions for iOS/Android SDKs etc...

Also worth mentioning the new navbar item types like versionDropdown etc that you can use so that it's not needed anymore to hardcode all the dropdown values in your config (dropdown is generated automatically)

I'm closing this, because I think we addressed the problem (maybe not the exact way you have in mind though).

As this is a bit new, please talk to me on Discord if you need help to set this up, as you would be an early adopter.

[vjpr]

@slorber I just tried multiple instances with a setup similar to https://github.com/facebook/docusaurus/blob/master/website/docusaurus.config.js#L61

But it errors while looking inside default:
docs/.docusaurus/docusaurus-plugin-content-docs/default/site-community-doc-1-md-87a.json'

but the file is in community instead:

docs/.docusaurus/docusaurus-plugin-content-docs/community/site-community-doc-1-md-87a.json'

The plugin seems to not be working with multiple instances...

---

Update - it's a bug

I was using a dash in the name and it broke it.

The following would search for files under foo instead of foo-bar.

   [
      '@docusaurus/plugin-content-docs',
      {
        id: 'foo-bar',
        path: 'foo-bar',
        routeBasePath: 'foo-bar',
      }
   ]

[slorber]

Thanks @vjpr , noted to take a look at this soon.
Do you mind opening a new issue for this?