Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(v2): docs versioning ❄️🔥 #1983

Merged
merged 36 commits into from
Nov 22, 2019
Merged

feat(v2): docs versioning ❄️🔥 #1983

merged 36 commits into from
Nov 22, 2019

Conversation

endiliey
Copy link
Contributor

@endiliey endiliey commented Nov 13, 2019

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

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("*")
  }
];

Blockers

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

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.
    image

  • I added lot of tests to ensure everything works perfectly

  • image

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

@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Nov 13, 2019
@docusaurus-bot
Copy link
Contributor

docusaurus-bot commented Nov 13, 2019

Deploy preview for docusaurus-2 ready!

Built with commit 5f88f8d

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

@docusaurus-bot
Copy link
Contributor

docusaurus-bot commented Nov 13, 2019

Deploy preview for docusaurus-preview ready!

Built with commit 5f88f8d

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

@endiliey endiliey added the pr: new feature This PR adds a new API or behavior. label Nov 13, 2019
} from './constants';

export default function(siteDir: string): Env {
const versioning: VersioningEnv = {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

title: 'Hello, World !',
description: `Hi, Endilie here :)`,
});
});

test('docs with custom permalink', async () => {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor Author

endiliey commented Nov 19, 2019

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 endiliey requested a review from yangshun November 19, 2019 06:54
@endiliey endiliey marked this pull request as ready for review November 19, 2019 09:25
break;
default:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@endiliey endiliey requested review from lex111 and wgao19 November 20, 2019 14:39
@endiliey endiliey changed the title feat(v2): docs versioning ❄️ feat(v2): docs versioning ❄️ Nov 22, 2019
@endiliey endiliey changed the title feat(v2): docs versioning ❄️ feat(v2): docs versioning ❄️🔥 Nov 22, 2019
Copy link
Contributor

@yangshun yangshun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@endiliey
Copy link
Contributor Author

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

@endiliey
Copy link
Contributor Author

🚀 Ship it ....

shipit

@endiliey endiliey merged commit 9829f56 into master Nov 22, 2019
@endiliey endiliey deleted the endi/versioning branch November 24, 2019 10:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants