feat(v2): docs versioning ❄️🔥

[endiliey]

Motivation

This is pretty much a WIP, but putting it here first since the nature of this PR is very big and its just easier to let people peek into it 😢. Up until 13/11 this is still the NodeJS part of the code though. and it is able to generate all the correct route and pages. You won't be able to check it in netlify preview yet because I haven't cut the docs lol Try it here: https://deploy-preview-1983--docusaurus-2.netlify.com/ with alpha.36 docs cut

• This also includes major refactoring on docs plugin especially on metadata. I try to avoid building object dynamically and prefer assigning all fields during object instantiation so that v8 can compile our code better. Also avoid hidden class transition
• I added a LOT of tests.
• Stronger docs typing

I try to make the folder structure as similar as v1 as possible for ease of migration and because directory structure is very related to CI. Changing versioned docs structure could reset Jest's translation back to 0 because crowdin don't understand if website/versioned_docs/version-1.0.0/hello.md is the same as website/<new_versioned_docs_directory_name>/hello.md

Overview

Directory structure

website/
├── sidebars.json          # sidebar for master (next) version 
├── docs/                # docs directory for master (next) version
│   ├── foo/         
│   │   └── bar.md       # https://mysite.com/docs/next/foo/bar
│   └── hello.md         # https://mysite.com/docs/next/hello  
│
├── versions.json             # file to indicate what versions are available 
├── versioned_docs/               
│   ├── version-1.1.0
│   │    ├── foo
│   │    │   └── bar.md      # https://mysite.com/docs/foo/bar
│   │    └── hello.md
|   │    
│   └── version-1.0.0
│        ├── foo
│        │   └── bar.md      # https://mysite.com/docs/1.0.0/foo/bar
│        └── hello.md
├── versioned_sidebars/
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
│
├── docusaurus.config.js
└── package.json

Path	Web route
docs/guides/hello.md	http://mysite.com/docs/next/hello
versioned_docs/version-1.1.0/hello.md	http://mysite.com/docs/hello
versioned_docs/version-1.0.0/hello.md	http://mysite.com/docs/1.0.0/hello

Tagging a new version

1. First, finsh your work on docs . A version always should be based from master.
2. Enter a new version number

yarn docusaurus docs:version 1.1.0

When tagging a new version, the document versioning mechanism will:

• Copy full docs/ folder contents into a new versioned_docs/version-<version>/ folder.
• Copy sidebars file and alter it. Saved as versioned_sidebars/version-<version>-sidebars.json.
• Place a new version number in versions.json

Files

Creating new files

1. Place the new file into correspondent version folder.
2. Include the reference for the new file into correspondent sidebar file, according version number.

Master docs

# the new file
docs/new.md

# edit the correspondent sidebar
sidebar.js

Older docs

# the new file
versioned_docs/version-1.0.0/new.md

# edit the correspondent sidebar
versioned_sidebars/version-1.0.0-sidebars.json

Linking files

• Remember to include the .md extension.
• Files will be linked to correct corresponding version
• Relative paths work as well

The [@hello](hello.md#paginate) document is great!

See the [Tutorial](../getting-started/tutorial.md) for more info.

Versions

Each subfolder in versioned_docs/ will represent a documentation version

Updating a existent version

You can update multiples docs versions at the same time. Because each docs/ subfolder represents specifics routes when published.

1. Edit any file.
2. Commit and push changes.
3. It will be published to the correspondent version.

Example: When you change any file from versioned_docs/version-2.6/, it will publish changes only for 2.6 docs version.

Changes from v1

• Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem
• We use snapshot now, every versioned docs does not depends on other version. It is possible to have foo.md in version-1.0.0 but it doesn't exist in version-1.2.0. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality )
• Unlike v1, The markdown header for each versioned doc is no longer altered by using version-${version}-${original_id} as the value for the actual id field. See scenario below for better explanation.

Example, you have a docs/hello.md.

---
id: hello
title: Hello, World !
---
Hi, Endilie here :)

When you cut a new version 1.0.0

In Docusaurus v1, website/versioned_docs/version-1.0.0/hello.md looks like this

---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---
Hi, Endilie here :)

In comparison, Docusaurus 2 website/versioned_docs/version-1.0.0/hello.md looks like this (exactly same as original)

---
id: hello
title: Hello, World !
---
Hi, Endilie here :)

Since we're going for snapshot and allows people to move (and edit) docs easily inside version. The id frontmatter is no longer altered, it's gonna be keep as it is. But internally it is set as version-${version}/${id}

• Refer to versioned_docs id as version-${version}/${id} (v2) instead of version-${version}-${original_id} (v1).

Why ? because in v1 there is a good chance someone created a new file with front matter id "version-${version}-${id}" that can conflict with versioned_docs id

Example, docusaurus 1 can't differentiate docs/xxx.md

---
id: version-1.0.0-hello
---
Another content

and website/versioned_docs/version-1.0.0/hello.md

---
id: version-1.0.0-hello
title: Hello, World !
original_id: hello
---
Hi, Endilie here :)

Since we don't allow / in v1 & v2 for frontmatter, conflict is less likely.

So v1 users need to migrate their versioned_sidebars file

Example:

{
  "version-1.0.0-docs": {
    "Test": [
+    "version-1.0.0/foo/bar",
-    "version-1.0.0-foo/bar",
    ],
    "Guides": [
+    "version-1.0.0/hello",
-    "version-1.0.0-hello"
    ]
  }
}

Have you read the Contributing Guidelines on pull requests?

yes

TODO (will keep updated)

• Generate all correct metadata and pages route if website has versioning
• Relative linking works in versioned docs
• Check no regression for basic site functionality
• Split generated routes by version so that routes looks like this

import React from "react";
import ComponentCreator from "@docusaurus/ComponentCreator";

export default [
  {
    path: "/",
    component: ComponentCreator("/"),
    exact: true
  },
  {
    path: "/docs/1.0.0/:route",
    component: ComponentCreator("/docs/1.0.0/:route"),
    routes: [
      {
        path: "/docs/1.0.0/foo/bar",
        component: ComponentCreator("/docs/1.0.0/foo/bar"),
        exact: true
      },
      {
        path: "/docs/1.0.0/foo/baz",
        component: ComponentCreator("/docs/1.0.0/foo/baz"),
        exact: true
      },
      {
        path: "/docs/1.0.0/hello",
        component: ComponentCreator("/docs/1.0.0/hello"),
        exact: true
      }
    ]
  },
  {
    path: "/docs/next/:route",
    component: ComponentCreator("/docs/next/:route"),

    routes: [
      {
        path: "/docs/next/advanced-plugins",
        component: ComponentCreator("/docs/next/advanced-plugins"),
        exact: true
      },
      {
        path: "/docs/next/using-plugins",
        component: ComponentCreator("/docs/next/using-plugins"),
        exact: true
      },
      {
        path: "/docs/next/using-themes",
        component: ComponentCreator("/docs/next/using-themes"),
        exact: true
      }
    ]
  },
  {
    path: "/docs/:route",
    component: ComponentCreator("/docs/:route"),
    routes: [
      {
        path: "/docs/foo/bar",
        component: ComponentCreator("/docs/foo/bar"),
        exact: true
      },
      {
        path: "/docs/hello",
        component: ComponentCreator("/docs/hello"),
        exact: true
      }
    ]
  },
  {
    path: "*",
    component: ComponentCreator("*")
  }
];

• Work on the cut version command (i will do in separate PR i think)
• Create an automated cli tools to convert v1 versioned docs to v2 structure ??? (doing this in separate PR, we dogfood the versioning first)
• Close DocSearch meta missing from the new released version #1792
• Docs (separate PR)

Blockers

• Generic Dropdown in Navbar like infima dropdown. (still waiting for mobile support in infima)
  

Syntax

// docusaurus/config.js
module.exports = {
  themeConfig: {
    navbar: {
      links: [
        {
          to: 'docs/docusaurus.config.js',
          label: 'docusaurus.config.js',
          items: [
            {
              to: 'docs/docusaurus.config.js#required-fields',
              label: 'Required Field'
            },
            {
              to: 'docs/docusaurus.config.js#optional-fields',
              label: 'Optional Field'
            }
          ]
        },
        // ... other links
      ],
    }
}

Test Plan

• All codes added is unit tested. We still maintain 100% docs plugin test coverage so regression from this PR in functionality is less likely.
  

• I added lot of tests to ensure everything works perfectly

• 

• TBD

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit 5f88f8d

https://deploy-preview-1983--docusaurus-2.netlify.com

[docusaurus-bot]

Deploy preview for docusaurus-preview ready!

Built with commit 5f88f8d

https://deploy-preview-1983--docusaurus-preview.netlify.com

[endiliey]

In future, i'll add translation to this env. So this PR is like a building block for translated docs already

[endiliey]

Deleted because actually frontmatter permalink feature has never been working nor is documented at v2 docs. This is remnant of munseo when docs functionality still generate flat route config..

[endiliey]

I think this should be eligible for first round of review. This PR is getting big already. What's left is quite isolated from current PR. I think better to do it in separate PR for ez review

• Cutting the docs version Edit: done, with 100% tests
• Converting v1 versioned_docs to v2 (I think that should be in separate PR). Or even better we dogfood the versioning first for v2 users only first)
• UI might need more tweaks. ?? There are blockers from infima such as waiting for mobile support on navbar dropdown
• Docs

[endiliey]

This is a never, All errors checking has been done in loadSidebars

[yangshun]

I'll just leave this here - https://twitter.com/iamdevloper/status/397664295875805184

[endiliey]

Let's ship it without the cut docs for now. To make this PR smaller and easy to look in the future

[endiliey]

🚀 Ship it ....