Docusaurus: [V2] Versioning Suggestions

[nebrelbug]

💥 Proposal

Hi! As I work on developing my Docusaurus site (https://squirrelly.js.org), I've noticed a few problems with the current versioning system.

1) Pages aren't versioned. This is a problem for me because on one page I host a live playground, and the syntax changes completely between the new and old libraries.
2) docusaurus.config.js isn't versioned. In my top bar, I link to different docs files. However, no matter what version I'm viewing, they always link to the latest docs (ex. /docs/ instead of docs/some-version/).
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.

With these problems in mind, I'd suggest having a public version variable. This could be provided to MDX files, similarly to withBaseUrl. It would also be nice if you could, in docusaurus.config.js, export a function that accepted a version string as the parameter.

Have you read the Contributing Guidelines on issues?

Yes

[daldridge-cs]

For item 3 above, I would like to see a hook that provides current version and a list of all versions:

import useVersion from `@docusaurs/core`; // ? or whatever module...

function myComponent() {
  const ( version, versions } = useVersion();
  return (... whatever ...);
}

I wrote something workable in my Lunr search plugin by using the useLocation hook from react-router and inspecting the path. Would be much nicer to have Docusaurus provide a mechanism.

[ghost]

Do you have different sidebars.js files for each version? I assume you do. Do you have a separate directory for each version? You can still point to reusable files.

Check the Discord post at the bottom from 02/14/2020: https://discordapp.com/channels/398180168688074762/632470883058843648

[nebrelbug]

@BoMiddleton yes, I have all of that set up and working.

The problem is that the links in the top navbar only point to the most recent version, rather than whatever version the user is currently looking at.

Additionally, I can't display different pages depending on the version (unless I parse the URL, which is rather complicated)

[amimas]

I don't think "pages" should be versioned. I think the idea of "pages" is different from "docs", which has a completely different requirement.

If "pages" are versioned, then the following pages become very confusing:

- index.html
- help.html
- contact.html

You'll have to maintain a separate list of pages that should be versioned and should not be versioned. Pretty soon this is going to get out of control...

Since this thread is about versioning in V2, then I think in your case you can write a custom react component and add that into a doc as part of normal mdx syntax.

[amimas]

docusaurus.config.js also should not be versioned. That's a repo-wide/site-wide configuration.

In my top bar, I link to different docs files. However, no matter what version I'm viewing, they always link to the latest docs

That sounds like a bug. That doesn't happen in V1

[nebrelbug]

@animas I agree we shouldn't have versioned pages, but I would love for there to be a way to fetch the current version inside a page, using something like useVersion()

[amimas]

I would love for there to be a way to fetch the current version inside a page, using something like useVersion()

I agree with this too. Just to be clear, I think you meant fetching the current version inside a "doc", not a page since... we're saying pages shouldn't be versioned and in that case, a page doesn't really have a context of what version you're looking at right now.

[lex111]

We will add the useVersion hook, the more we need it to show the version of docs in navbar.

[nebrelbug]

@lex111 let me know if there's anything I can do to help

[lex111]

@nebrelbug well, if you want to implement a similar hook and create the corresponding PR - it would be very very cool :smiley:

[nebrelbug]

I'll take a look, but I wouldn't be able to do any work until Friday :smile:. I would enjoy contributing though -- though I've found several bugs and given feedback, I have yet to earn the Contributor badge by my name :)

[yangshun]

@nebrelbug These are hard problems you've mentioned.

Pages aren't versioned

We don't intend to add support for this. Versioning shall be a docs-only feature. Notice that the current versioned docs path is docs/<version>/some-markdown. This is intentional and by design. We want to support the use case of having multiple sets of docs, each with its own version. For example, you're building a mobile SDK for both iOS and Android and want them to have different versions.

The current docs design is a little flawed. We allow for multiple doc plugins but the versioning approach and commands assume only one docs plugin. In future we should have a namespace for each set of docs, which you define as options passed into the docs plugin. So useVersion() would have to take in a parameter for the namespace, e.g. useVersion('iOS'), useVersion('Android').

[slorber]

Some things worth mentioning:

one deployment per version

If your docusaurus site changes too much across versions and having only docs versioned is a problme, you could also handle the versioning outside of docusaurus, with separate immutable deployments.

This is the strategy of the ReactJS website.
This url redirects to a separate Netlify deployment: https://fr.reactjs.org/version/16.3
The main site only handle the current version: https://fr.reactjs.org/versions/

This strategy gives the opportunity to affect current version without the risk of breaking something that worked on an older version.

useVersion() can only work in docs/sidebar comps

There's currently no concept of "global current version", only docs/sidebar version.
Such a hook would only work when the user is browsing a docs page.

On global pages like /live-editor or /contact, there's no version in the url, so we don't know what is the version. At most, we could store the last version browsed by the user in some kind of storage, but that seems hacky (probably possible in userland).

global site dependencies

If you have a live editor like react-live somewhere in the app, in 5 different versions, it's unlikely you'll be able to provide your lib's code in the editor scope for the 5 different lib versions (it might be possible with yarn resolution to load a lib in 2 different versions).

It might be better to publish the live playground as a separate app, and integrate it in your doc.

For example you could use a unique page, with tabs to select the playground version, and load an iframe or something.

If this tab system is annoying, you can also create a versioned doc on which you embed the playground iframe thanks to MDX.

[nebrelbug]

@slorber I use NPM/Yarn package aliases (https://stackoverflow.com/questions/26414587/how-to-install-multiple-versions-of-package-using-npm) on https://squirrelly.js.org/playground along with tabs to allow users to choose the version of the playground, which means I don't have to use an iframe.

[krillboi]

I'd personally also love a version hook, so bump to this!

Also, are there any plans to implement versioning of assets like images, as mentioned here in #1257?

[bravo-kernel]

Bumping this because we desperately need simple versioning ❤️

[slorber]

@krillboi that's something I'd like to add. Will see how we could add a provider on top of a whole version.

@bravo-kernel what is simple versioning to you? What's missing that you need in D2?

[bravo-kernel]

Awesome @slorber. I have tried to explain this on multiple occasions and always failed to get it across. Perhaps this real world example will work:

First the situation:

• we have a separate repository that holds the code (Powershell Pester)
• we have a separate repository for our D2 documentation (Powershell Pester Docs)
• we once created the D2 website with some pages auto-generated by parsing the source code repo, at that time v4
• time has passed
• now the source repository is v5 (and will stay v5 for a long time)

What we would like:

• create a copy/cut of our current D2 website
• name that copy v4
• update D2 master to represent v5
• use D2 master as current (just as would be the case if we only had one version)

What we do not want

• follow the workflow derived from existing next (because for us, v5 is not next version, it's the actual and current one, will not significantly change)

Hope that makes sense. If you have any additional questions please let me know

[slorber]

@bravo-kernel

Do you still update v4 docs? If not, you could simply create a docs-v4 branch, deploy it to netlify as a non-versioned D2 deployment, like v4.pester.dev, and have v5 be the master branch (still without D2 versioning).

If you want v4 and v5 as the same unified SPA under same domain: as far as I understand, what you would like is to have /docs instead of /docs/next ? ie v5 is the current "work in progress version", and you want to edit files in ./docs directly?

IE somehow it's a workflow where you have already released v5 + v5 initial doc, but you still do a lot of documentation work, so that you don't yet want to copy these files to the versioned folder?

This feature makes sense to me, we could allow to configure currentVersion: 'next'

[bravo-kernel]

Exactly, this:

If you want v4 and v5 as the same unified SPA under same domain: as far as I understand, what you would like is to have /docs instead of /docs/next ? ie v5 is the current "work in progress version", and you want to edit files in ./docs directly?

[bravo-kernel]

And updates to the v4 would then have to be done in /docs/v4 but that makes sense from an end-user perspective. Seems to be the location where one expects them to be.

[amimas]

This feature makes sense to me, we could allow to configure currentVersion: 'next'

☝️ This doesn't quite make sense to me, to be honest. I find it a bit confusing when I read that config.

From the example that @bravo-kernel mentioned, my understanding is "v5" is their "next version" if it's not fully completed yet or there isn't a "next version" after v5 (as of right now). So, the existing setup/process/workflow of Docusaurus still make sense to me.

Maybe it's just a matter of being able to "label" the next release. That way, in the versioning page/list, "next release" is named "v5" instead of hard coded to "master/unreleased". So, technically you're not creating the "v5" version in Docusaurus, because it's still "in-progress".

Not sure if that helps but thought I'd put it out there. I like simplicity and hopefully Docusaurus V2 features does not become over-complicated due to multitude of options that becomes hard to maintain down the road.

[krillboi]

I have a little caveat to add. Let's say I have 3 versions: 1.0, 2.0 and 3.0. This would produce links following this structure:

/docs/1.0/introduction.mdx
/docs/2.0/introduction.mdx

The problem now arises with 3.0. Since this is current stable version, you will access the introduction doc with simply /docs/introduction.mdx but as far as I can tell the link /docs/3.0/introduction.mdx is not created. This is a problem if you release your application/product with direct links to the introduction article with the correct version, i.e. I release 1.0 of my product which contains a link to /docs/1.0/introduction.mdx, then I release 2.0 with /docs/2.0/introduction.mdx.

Now I release 3.0 where /docs/3.0/introduction.mdx won't work. If I link with /docs/introduction.mdx it always links to current version which means when 4.0 is released, links inside the 3.0 product will link to a wrong version.

Not sure if that was clear enough but TLDR: all versions should have a corresponding link to its version, also if it happens to be current version.

[bravo-kernel]

As much as I understand that most examples and caveats can be valid, they also show the complexity that we (as requesters of simple versioning) are trying to avoid.

[slorber]

Hey everyone.

I believe we already addressed some things of this issue.

• The pages and site config are not going to be versioned.

• The docs plugin can be "multi instance": https://github.com/facebook/docusaurus/issues/2528#issuecomment-674112728

• The new navbar items "versionDropdown" and "docsVersion" should cover your need. A useVersion hook is likely to not be straightforward to use because it would require passing the docs plugin instance id, + it would always return undefined on pages for examples. If you think it's not enough, please discuss with me your specific usecases in depth. We have hooks in the docs plugin but we consider them "internal" for now. If you decide to use them, please show me how.

There is an RFC here that should cover the issues related to /docs/next, /docs etc... let's move the conversation here but please let me know if you think something is not resolved.

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

[slorber]

In case you are interested to check these "internal" hooks, see the DocsVersionNavbarItem.tsx component, which permit to display in the navbar the current version, with a fallback to the "latest version".

As you see, it's not so straightforward to use as useActiveVersion will not necessarily return a result if you are on a page (like the homepage), on the 404/search page etc... We need a fallback to always display something useful.

import React from 'react';
import DefaultNavbarItem from './DefaultNavbarItem';
import {useActiveVersion, useLatestVersion} from '@theme/hooks/useDocs';

const getVersionMainDoc = (version) =>
  version.docs.find((doc) => doc.id === version.mainDocId);

export default function DocsVersionNavbarItem({
  label: staticLabel,
  to: staticTo,
  docsPluginId,
  ...props
}) {
  const activeVersion = useActiveVersion(docsPluginId);
  const latestVersion = useLatestVersion(docsPluginId);
  const version = activeVersion ?? latestVersion;
  const label = staticLabel ?? version.label;
  const path = staticTo ?? getVersionMainDoc(version).path;
  return <DefaultNavbarItem {...props} label={label} to={path} />;
}

Unless you use docs multi instance, docsPluginId="default" (undefined should work too)