Single page versioning

[sta-szek]

Hi guys, i read

• https://docusaurus.io/docs/versioning
• https://docusaurus.io/docs/next/docs-multi-instance#use-cases
• Multiple components - single docs repo #3332

and still cannot get answer for my concerns.

I would like to achieve versioning, but for single page only because:

• we have huge docs, which does not need to be versioned -> if we copy paste directories for everything we will just increase complexity and size
• other pages might require another form of versioning in future (e.g. Event Guidelie vs API Guidline might have different versions)

And, I would like to avoid new category on Top Bar -- i would like to include the page in the docs starndard sidebar.

my idea was to create use the docs plugin again:

    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'starters',
        path: 'starters',
        routeBasePath: 'starters',
        showLastUpdateAuthor: true,
        showLastUpdateTime: true,
        remarkPlugins: [
          remarkMermaid,
          simplePlantUML
        ],
      },
    ],

but i cannot make it working.

so my questions:

1. Is that possible to version single page?
2. If we use another docs plugin, can we add the "new docs" to docs sidebar?

[slorber]

Hey, I'm sorry but this issue is not detailed enough for me to understand what you are trying to do.

Please show me an example file-system tree that you would like to have with all the md docs and versions, and how it should be represented in term of UI / Sidebar etc... Use https://excalidraw.com/ for mockups if needed. A concrete example is better than text.

I would like to achieve versioning, but for a single page only because

other pages might require another form of versioning in future (e.g. Event Guidelie vs API Guidline might have different versions)

You can create a doc plugin instance for a single page if you want, but that seems suspicious to me.

If all your pages have different versioning schemes (like event guideline in v3 and API guidelines in v7) you'd rather use a single plugin instance and just create multiple files event-guideline-v1.md event-guideline-v2.md event-guideline-v3.md

The versioning feature of Docusaurus mostly make sense when you want to version a set of docs

And, I would like to avoid new category on Top Bar -- i would like to include the page in the docs starndard sidebar.

A sidebar can only reference docs of its current version, because a sidebar is also versioned alongside the versioned docs.
The sidebar is what link docs together and creates an ordering between docs. If you are on a doc in v1, then the next doc will also be in v1. A doc in v2 will link to next/previous doc in v2.

It does not make sense by default to link event guidelines in v2 to API guidelines in v7 as those have separate versions. Sidebar default linking strategy is to link docs of the same version together with next/previous, not interleaving versions

However, you can still create regular static links in any sidebar: https://docusaurus.io/docs/sidebar#sidebar-item-link in which can any page can link to any page through the sidebar.

but i cannot make it working.

It is not clear to me what you can't make work exactly. I can't help if you don't tell me :)

Is that possible to version single page?

Yes but I'm not sure it's what you should do because a version is meant to be used for a set of docs with next/previous navigation inside that versioned doc set

If we use another docs plugin, can we add the "new docs" to docs sidebar?

Sidebar is for docs of the same version, but you can add any static link in such sidebar

---

If all your docs have different version schemes/lifecycles, you'd rather not use the versioning feature in the first place imho, and just create multiple copies of your versioned doc in the ./docs folder directly.

[sta-szek]

hi @slorber !
thanks for replay.

maybe better will be to show you screenshot of that i have and then just paint what is missing there.

So here is our docs:

and actually everything is explained there.
i want to keep exactly what i have, but the single starters (Reference) page should be versioned, so we can version starters docs without versioning whole docs.

is that currently possible? if so, can i ask for example / explanation ?

otherwise, if that is not possible, what other approach we could take?

thanks

[slorber]

Sorry but I don't understand what you mean here:

What is supposed to appear in this circle? A link? A dropdown with versions?

If this page is supposed to display the current sidebar (getting started, security...) then it should rather be part of the docs of that sidebar, because regular pages (src/pages) don't have a sidebar.

Creating an extra doc instance for starters is not ideal for your use case. It means you'd have to maintain 2 sidebars files with quite identical content (the "starters doc instance" would have to use regular static links instead of doc ids because one instance can't ref the docIds of another: they are isolated).

I'm still not sure to understand the problem but what I would try, assuming you want to link in priority to the latest version:

• create docs/starter-v1.md
• create docs/starter-v2.md
• create docs/starter-v3.md
• Sidebar links to doc id=starter-v3
• Create a "static" hardcoded navbar dropdown with sub-items linking to starter-v1/v2/v3.
• Make dropdown button link to v3.

BTW, we'd be happy to showcase SAP using Docusaurus here :) https://docusaurus.io/showcase