RFC: docs version configurations

💥 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 https://github.com/facebook/docusaurus/issues/3391)

Does this make any sense?

Edit: funny because 2 years ago @endiliey already discussed about version aliases + Algolia search here: https://github.com/algolia/docsearch-configs/issues/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?

https://github.com/facebook/docusaurus/issues/3212

Version warning banners

https://github.com/facebook/docusaurus/issues/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.

[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 😃

[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).