RFC: docs version configurations

[slorber]

💥 Proposal: docs version configurations

A complete docs plugin cleanup/refactor (#3245) is going to make it much easier to add more flexibility to the docs plugin.

This could be the time to introduce version-specific configuration.

I'd like to have the opinion of the community of what all the usecases are, so that we can craft a good API to cover them.

Existing version metadata:

As of today, the medatata of the versions are mostly inferred by conventions, from what has been done on Docusaurus v1.

The things we can potentially configure easily are currently:

export type VersionMetadata = {

  // name in versions.json, not configurable
  versionName: string;

  // label used by themes
  versionLabel: string;

  // URL path of the version, like /docs/1.0.0
  versionPath: string;

  // relative path to the docs folder, like versioned_docs/1.0.0
  docsDirPath: string;

  // relative path to the sidebars file, like versioned_sidebars/1.0.0.json
  sidebarFilePath: string;

};

Note: the ./docs folder has versionName="current", label="next", path="/next" (retrocompatibiilty). This current version is the version we'll consider the most up-to-date, and copy from when using the versioning cli.

I think all these metadatas should be configurable, including for the "current" version.

Note: users might be able to configure custom file system paths for each version. But when using the cli to create a new version, we'll likely output it in the usual location versioned_docs/version-<newVersionName> and versioned_sidebars/version-<newVersionName>-sidebars.json. Is that ok or this part should also be configurable?

Current version advanced configurations

Regarding the ./docs folder, some users have reported that this is confusing for contributors, as the version it belongs to is "implicit" (not in the dirname).

Some users have reported that it could be useful to NOT have a ./docs folder, and simply having the ./versioned_docs with explicit version numbers in each folder.

For example:

versioned_docs/version-5.0.0 
versioned_docs/version-4.0.0
versioned_docs/version-3.0.0 
versioned_docs/version-2.0.0 
versioned_docs/version-1.0.0 

This is more explicit for an user to know which folder to contribute to exactly.

Should we allow to use currentVersion.docsDirPath = "versioned_docs/version-5.0.0"?

Or maybe should we also allow to have a site without any "current" version? In such case, when using the versioning cli, how do we know which folder to copy from?

I think an option like addCurrentVersion: false would be good, and the cli problem can be solved too: yarn docusaurus docs:version --from=1.0.0

Important: for git it may be better to have a fixed folder for the current version, because cp does not preserve any history at all (git cp does not exist), so if you bootstrap v6 by coping v5 folder, you have an empty history on v6. I think it's better to have a ./docs folder on which you can see the full history.

Main version

Currently, we have the "last version" concept but this is a bit weird. We consider the latest version the one at the top of the versions.json file.

This is the version that:

• the version dropdown will lead to in priority
• will be suggested by the version warning banners
• will be available at the "root" URL path of the docs plugin: /docs/.

We should be able to configure which version is the "main/recommended one" that we'll link to in priority. Not sure if "main/recommended" is a good naming, if you have a better idea...

Version aliases

Something that has been annoying for some users, is that the "latest" version has an URL like /docs/myDoc while others versions are /docs/<versionPath>/myDoc.

It is particularly annoying because there is no future-proof way to have a permalink a doc of this specific version, as this is an URL for which the doc will "change version" over time.

For these reasons, I think we want to ALWAYS have URLs like /docs/<versionPath>/myDoc, for all versions. These would be the canonical URLs the versioned docs.

But we also need a way to keep the behavior of having URLs like /docs/myDoc keep working over time, and it would be cool to be able to create aliases like /docs/stable/myDoc, /docs/canary/myDoc etc...

To handle these scenarios in a flexible way, I suggest introducing version aliases

const versionAliases = [
  { versionName: "1.0.0", aliasPath: `/stable`, type: "duplicate" },
  { versionName: "2.0.0", aliasPath: `/`, type: "redirect" }
];

With the above configuration:

• /docs/stable/myDoc would be a copy of the content available at /docs/1.0.0/myDoc (with canonical URL correctly set)
• /docs/myDoc would redirect (client-side) to /docs/2.0.0/myDoc

For retrocompatibility reasons, this default alias would be created:

const versionAliases = [
  { versionName: versions[0], aliasPath: `/`, type: "duplicate" },
];

So this means that the doc you currently have at /docs/myDoc will now also exist at /docs/<latestVersion>/myDoc (the "original")

Note, aliases should also be used to register the agolia facets, so that it's possible to search in "latestVersion", which could permit to avoid breaking the search engine after a new release (see #3391)

Does this make any sense?

Edit: funny because 2 years ago @endiliey already discussed about version aliases + Algolia search here: algolia/docsearch-configs#469

Dev: browse current docs by default

When in dev mode docusaurus start, process.env.NODE_ENV === 'development' etc, it can be confusing for contributors to not see their docs changes immediately, as by default the docs dropdown lead to the "latest version" instead of /docs/next.

I think this would be resolved by using different version aliases in dev/prod, but requires a big more config. Can we make this more straightforward?

#3212

Version warning banners

#3013

There is a need to be able to configure the version warning banners

The current system is not very flexible. All banners lead to the latest version of versions.json (the one at the top), and the messages are hardcoded.

Version entrypoint: mainDocId ?

The doc through which we should enter the version.

For example if we click the versions dropdown in the navbar, where does this lead to exactly?

The algo is currently: mainDocId = "homeDocId" ||doc with slug: /|| firstDocOfFirstSidebar

Note: the global homeDocId is going to be deprecated, as we need to be able to configure this per version. I think slug: / frontmatter is good enough and don't feel that we really need a version.homeDocId feature. What do you think?

Is there a need to use a custom doc as a version entrypoint? (I mean a doc that wouldn't be the first doc of the first sidebar, nor the doc at the root version path... )

Move sidebars file to docs/sidebars.json?

I think there's no additional value to separe the sidebars from the docs folder. It creates additional configuration options that I suspect are not very widely used and not very useful. I personally don't like the versioned_sidebars folder.

What about having this instead?

./docs/sidebars.js
./versioned_docs/version-2.0.0-alpha.54/sidebars.json

I'm curious here if people have use cases for dynamic sidebars using JS code to generate the sidebar structure?

Also not a fan of the fact that ids become prefixed by the version in the sidebars files: like version-2.0.0-alpha.54/introduction. As we already know the version of the sidebars file (due to its folder), I see no value prefixing these ids.

That can be done later because all this would be a breaking change, and we can live with the current state, but curious to have your opinion.

Configuration location

Do we want to configure a version through the site config file?

Or do we want a docsFolder/versionConfig.js file? (in which we could eventually put the sidebars too)

Version archiving

Not totally related to configuration, here's an RFC for a version archiving feature

---

Please tell me all the version configuration options you'd like to have, and what kind of API you would find convenient to use.

[bravo-kernel]

Thanks for taking the time to prepare this PR, much much appreciated. As an end-user I can't really contribute other than that it would be most useful if we could rename/label next (and yes I did see that note about retro-compatibility).

[slorber]

Thanks, I've added more content but yes we should definitively be able to configure the path/label for ./docs if you don't like /next and Next :)

[Dannyholt]

This looks awesome!

[markerikson]

I think this sounds like it's in the right direction.

Right now React-Redux is the only one of the Redux docs sites still on DSv1, specifically because it's the only one that deals with versioned docs. Be happy to use PRs there as a testbed for trying out improvements to DS's versioning setup.

[zepatrik]

A short case study on how we use the version features:
Docs are written for the current master in the ./docs directory. This is confusing for contributors, especially because of the problem described in #3212.
When there is a release we pin the version and copy the ./docs content to ./versioned-docs. Having the current master docs is a nice feature for us as we can have discussions with the community before releases. We have to write the docs beforehand anyway.

Also good proposals I don't have to add anything are:

• permalinks through version aliases
• adding customization for warning banners
• Move sidebars file to docs/sidebars.json

[joshribakoff]

It's probably out of scope, but in addition to the notes I left on #3294 one other thing I wanted to point out that's worth considering that as a user I'd maybe like to include code snippets on my home page, which could differ between versions.

[omry]

I'm curious here if people have use cases for dynamic sidebars using JS code to generate the sidebar structure?

One use case is that we are disabling some sidebar items based on environment variables to hide some internal (but not sensitive) docs.
the same website is hosted both externally and internally, and internally it is built with that environment variable set.

In fact, the versioned sidebars not being dynamic is causing issues with that.

[eriveltonelias]

Note: the ./docs folder has versionName="current", label="next", path="/next" (retrocompatibiilty). This current version is the version we'll consider the most up-to-date, and copy from when using the versioning cli.

I think all these metadatas should be configurable, including for the "current" version.

Note: users might be able to configure custom file system paths for each version. But when using the cli to create a new version, we'll likely output it in the usual location versioned_docs/version-<newVersionName> and versioned_sidebars/version-<newVersionName>-sidebars.json. Is that ok or this part should also be configurable?

Current version advanced configurations

Regarding the ./docs folder, some users have reported that this is confusing for contributors, as the version it belongs to is "implicit" (not in the dirname).

Some users have reported that it could be useful to NOT have a ./docs folder, and simply having the ./versioned_docs with explicit version numbers in each folder.

For example:

versioned_docs/version-5.0.0 
versioned_docs/version-4.0.0
versioned_docs/version-3.0.0 
versioned_docs/version-2.0.0 
versioned_docs/version-1.0.0 

This is more explicit for an user to know which folder to contribute to exactly.

I think it will good to remove the /docs folder and keep only related to version-specific because it is too confusing for people who want to contribute the first time or don't know how docusaurus handle it.

Should we allow to use currentVersion.docsDirPath = "versioned_docs/version-5.0.0"?

Or maybe should we also allow to have a site without any "current" version? In such case, when using the versioning cli, how do we know which folder to copy from?

I think an option like addCurrentVersion: false would be good, and the cli problem can be solved too: yarn docusaurus docs:version --from=1.0.0

if the user can choose which folder to copy from when running the cli the current version will not be necessary here, or it's used in other places?

Version aliases

const versionAliases = [
  { versionName: versions[0], aliasPath: `/`, type: "duplicate" },
];

So this means that the doc you currently have at /docs/myDoc will now also exist at /docs/<latestVersion>/myDoc (the "original")

Does this make any sense?

that's super exciting 😍

Version warning banners

The current system is not very flexible. All banners lead to the latest version of versions.json (the one at the top), and the messages are hardcoded.

can we make this customizable on each version folder? will be nice the folder config file you have an option to say is maintained or not and also a different message too.

[markerikson]

I think it will good to remove the /docs folder and keep only related to version-specific

Totally disagree on this.

A lot of our docs are not version-specific (installation, tutorial, usage guide, etc).

Also, I want to have a /docs folder as the obvious place where the "latest" docs live.

[eriveltonelias]

I think it will good to remove the /docs folder and keep only related to version-specific

Totally disagree on this.

A lot of our docs are not version-specific (installation, tutorial, usage guide, etc).

Also, I want to have a /docs folder as the obvious place where the "latest" docs live.

if you create on versioned_docs a fixed version? like current and with version aliases you can handle all permanent links, so if you do that will follow the same behavior as today, it's just my option :)

[slorber]

Thanks for the feedback everyone ;)

---

@markerikson

A lot of our docs are not version-specific (installation, tutorial, usage guide, etc).

It's something new on which I'd like to onboard some users and get feedbacks before writing official docs, but we have "multi docs instance" support, and it's already live on our website. Here's "community docs", a standalone, unversioned docs instance:

https://v2.docusaurus.io/community/support

---

@eriveltonelias

I think it will good to remove the /docs folder and keep only related to version-specific

We are currently trying to migrate the RN website, and maintaining a proper git history is something important. Unfortunately, there is no "git cp" command that permit to init one file from another, duplicating at the same time its history.

We'll likely support the flow you want, but not as a default, as the drawback of having the "main docs" changing path each version is that it's likely harder to maintain history, and may require some git gymnastic.

Ie you can't just create react-navigation/v6 from react-navigation/v5, and expect v6 docs to have a full history preserved, because by default, they would have just 1 entry unfortunately.

[eriveltonelias]

Ie you can't just create react-navigation/v6 from react-navigation/v5, and expect v6 docs to have a full history preserved, because by default, they would have just 1 entry unfortunately.

gotcha, that makes sense. :) if we don't keep the full history preserved it will be a huge issue for all use cases? I'm just curious about that because on react-navigation I don't think we expect to have a full history preserved of commits when copy v5 to v6.

[slorber]

For rnav v4-v5 we probably don't care as it's a rewrite.

For RN website it's clearly a blocker that 2 maintainers of the site rapidly reported :)

[slorber]

Hi there.

Just wanted to let you know that alpha 62 has been published and gives the ability to configure per version paths/labels. The rest of this RFC will come later.

#3357

https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.62

[omry]

Thanks @slorber, can you point to a doc page explaining how to use this?
I know it's annoying (I am facing the exact same issue with Hydra), but I think release notes should contain links to relevant doc pages to improve adoption of new features.

[slorber]

You can check this:

https://v2.docusaurus.io/docs/versioning#figure-out-the-behavior-for-the-current-version
https://v2.docusaurus.io/docs/using-plugins#docusaurusplugin-content-docs

[krillboi]

The version aliases part makes me very happy!

[riccardozambito]

You can check this:

https://v2.docusaurus.io/docs/versioning#figure-out-the-behavior-for-the-current-version
https://v2.docusaurus.io/docs/using-plugins#docusaurusplugin-content-docs

Sorry but I don't understand some aspects of the new feature. if I may ask:

1. Have I to create my versions in order to have "versioned_docs" folder?
2. What will be the structure of folders related to the example of the documentation?

Thanks!

[slorber]

@riccardozambito your questions do not seem to be related to new features planned in this RFC, so it may be preferable to open a separate issue (or ask for help on Discord), as this issue focus on the new versioning capabilities, not docs versioning in general. Discussions on this issue are related to people already having a versioned site, and having pain points that they would like to be solved.

1. The versioned_docs folder is not something new, and you indeed have to create a version with the cli to get this folder created, otherwise your site is not versioned and this folder is not needed.

2. Sorry but I don't understand your question, but maybe looking at source code of existing versioned Docusaurus 2 sites would help

[jknoxville]

I'm curious here if people have use cases for dynamic sidebars using JS code to generate the sidebar structure?

We do this in facebook to differentiate internal builds of websites from public ones, based on env variables e.g. here and here.

At the moment this works fine for unversioned docs, but not for versioned ones due to the frozen .json file.
For that reason I'd much prefer that versioned sidebars files maintain the same structure as non-versioned ones (.js files).

[slorber]

@jknoxville thanks for letting me know. The tradeoff is that if we copy the sidebars.js file directly, it is likely that relative paths used for imports will break. Should we create a json file, and let you change it back to a js file if needed? Or should we write a js file and maybe this would break imports?

I guess we could rewrite relative imports and process a bit the AST, but this is significantly more work compared to just copying a file :)

I guess the @site/... import alias would be a good thing to use in sidebar files so that the file would work no matter its FS location.

Maybe we should implement a way to filter sidebar items (or even all created pages) directly from config ?

[omry]

Maybe we should implement a way to filter sidebar items (or even all created pages) directly from config ?

You mean at runtime or at build time?

[jknoxville]

@slorber

Should we create a json file, and let you change it back to a js file if needed? Or should we write a js file and maybe this would break imports?

Out of those two options, the second sounds preferable to me. I presume relative imports are rare so most of the time it'll be fine, but in cases where they are needed, it will fail loudly, and someone will have to fix it, rather than a silent "failure" of the json file just containing the wrong things. With guidance to always import from "@site..." then it would be better still with no manual changes necessary.

Maybe we should implement a way to filter sidebar items (or even all created pages) directly from config ?

I think that would be great, though it might somehow need to be able to cope with "nested" sidebars in other files. We have some places like this where sections of the sidebars are sourced from different files, to prevent the internal sidebars themselves from being public.

[TomPeirs]

From #2302 (comment)

3. There's no way to get the current version in your React Components, so, for example, on the Docusaurus site, the link next to Docusaurus always reads alpha.43, no matter what version you're currently viewing.

This is still relevant.

I'm trying to modify the link on my index page to my doc based on the active version.
For instance, currently when you are on https://docusaurus.io/docs/ and change to 2.0.0-alpha.75 , but on the index page press get started button then you will go to the latest beta version docu.

I think it would make sense to bring attention to this even though the pages are not versioned, there should be a possibility when you press "Get Started" on the docusaurus landing page, that you go to the corresponding versioned documentation and not the latest/current.

[slorber]

Agree @TomPeirs , we could expose a hook permitting to get a link to a docId of the same version in user pages (somehow similar to the navbar item type doc)

[TomPeirs]

we could expose a hook permitting to get a link to a docId of the same version in user pa

This would be really interesting.
I was spending my time yesterday to understand why this logic was working in the navbar, and noticed there we simply pass the docId. Would indeed be great to be able to pass this from your react component.

[slorber]

FYI the version banner will be configurable on a per-version basis, so you may not need to swizzle the component anymore to disable that banner:

#5052

[Josh-Cena]

@slorber Anything you see in this proposal that is still lacking?

[slorber]

There are a few things discussed in this issue that are not yet implemented: from small additional options to moving sidebars.json inside /docs to version aliases

But this issue is quite large so I guess we can close it and eventually open more dedicated issues if anyone requests something mentioned in that issue.

[tisonkun]

@slorber Today I meet a requirement that exactly needs the version alias feature - for your information :)

See also apache/pulsar#17438.

[fmassot]

Same for Quickwit, having the alias feature would be awesome.

[slorber]

@fmassot can you explain how this feature should behave in your case?

A workaround that could work in a post-build step:

cp -R build/docs/1.0 build/docs/<my-alias-name>

I think if we ever build this feature, we'll do something like that: it would be much faster compared to rendering the page again with another path.

[tisonkun]

FYI - I resolve this issue by server-side redirections.

https://github.com/apache/pulsar-site/blob/a92f7003d65130b1415b9534e9b8860cd3d12512/static/.htaccess#L19

It's not perfect because I need to update the redirections every time a new release out. But it is somehow an Apache Web Server limitation and can be anyway resolved with an external script and automation.

[slorber]

Thanks @tisonkun

I re-opened a dedicated issue because the version aliasing thing comes back quite often in discussions.

If we need to implement this, please give my as much details as you can here: #9049