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

* wip: versioning

* wip again

* nits lint

* refactor metadata code so that we can have inobject properties optimization, fix typing

* remove buggy permalink code

* modify versioned docs fixture such that foo/baz only exists in v1.0.0

* refactor metadata.ts so that there is less transformon object

* more refactoring

* reduce test fixtures, refactoring

* refactoring readability

* finish metadata part

* refactor with readdir

* first pass of implementation

* fix mdx laoder

* split generated routes by version for performance & smaller bundle

* test data for demo

* refactor with set

* more tests

* typo

* fix typo

* better temporary ui

* stronger typing & docsVersion command

* add 100% test coverage for docsVersion command

* more test and delete manual docs cut

* cut 2.0.0-alpha.35 docs

* cut alpha.36 instead

* copyright

* delete versioned docs

* stronger test on metadata

* update typo

packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/doc2.md

@@ -0,0 +1,6 @@
+### Existing Docs
+
+- [doc1](subdir/doc1.md)
+
+### With hash
+- [doc2](doc2.md#existing-docs)

packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/versioned_docs/version-1.0.0/subdir/doc1.md

@@ -0,0 +1,2 @@
+### Relative linking
+- [doc1](../doc2.md)

packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__snapshots__/linkify.test.ts.snap

@@ -34,6 +34,15 @@ exports[`transform to correct links 1`] = `
 - [doc2](/docs/doc2)"
 `;
 
+exports[`transforms absolute links in versioned docs 1`] = `
+"### Existing Docs
+
+- [doc1](/docs/1.0.0/subdir/doc1)
+
+### With hash
+- [doc2](/docs/1.0.0/doc2#existing-docs)"
+`;
+
 exports[`transforms reference links 1`] = `
 "### Existing Docs
 
@@ -55,3 +64,9 @@ exports[`transforms reference links 1`] = `
 [image1]: assets/image1.png
 "
 `;
+
+exports[`transforms relative links in versioned docs 1`] = `
+"### Relative linking
+- [doc1](/docs/1.0.0/doc2)
+"
+`;

packages/docusaurus-plugin-content-docs/src/markdown/__tests__/linkify.test.ts

@@ -9,14 +9,19 @@ import fs from 'fs-extra';
 import path from 'path';
 import linkify from '../linkify';
 import {SourceToPermalink} from '../../types';
+import {VERSIONED_DOCS_DIR} from '../../constants';
 
 const siteDir = path.join(__dirname, '__fixtures__');
 const docsDir = path.join(siteDir, 'docs');
+const versionedDir = path.join(siteDir, VERSIONED_DOCS_DIR);
 const sourceToPermalink: SourceToPermalink = {
   '@site/docs/doc1.md': '/docs/doc1',
   '@site/docs/doc2.md': '/docs/doc2',
   '@site/docs/subdir/doc3.md': '/docs/subdir/doc3',
   '@site/docs/doc4.md': '/docs/doc4',
+  '@site/versioned_docs/version-1.0.0/doc2.md': '/docs/1.0.0/doc2',
+  '@site/versioned_docs/version-1.0.0/subdir/doc1.md':
+    '/docs/1.0.0/subdir/doc1',
 };
 
 const transform = filepath => {
@@ -27,6 +32,7 @@ const transform = filepath => {
     docsDir,
     siteDir,
     sourceToPermalink,
+    versionedDir,
   );
   return [content, transformedContent];
 };
@@ -70,3 +76,23 @@ test('transforms reference links', () => {
   expect(transformedContent).not.toContain('[doc2]: ./doc2.md');
   expect(content).not.toEqual(transformedContent);
 });
+
+test('transforms absolute links in versioned docs', () => {
+  const doc2 = path.join(versionedDir, 'version-1.0.0', 'doc2.md');
+  const [content, transformedContent] = transform(doc2);
+  expect(transformedContent).toMatchSnapshot();
+  expect(transformedContent).toContain('](/docs/1.0.0/subdir/doc1');
+  expect(transformedContent).toContain('](/docs/1.0.0/doc2#existing-docs');
+  expect(transformedContent).not.toContain('](subdir/doc1.md)');
+  expect(transformedContent).not.toContain('](doc2.md#existing-docs)');
+  expect(content).not.toEqual(transformedContent);
+});
+
+test('transforms relative links in versioned docs', () => {
+  const doc1 = path.join(versionedDir, 'version-1.0.0', 'subdir', 'doc1.md');
+  const [content, transformedContent] = transform(doc1);
+  expect(transformedContent).toMatchSnapshot();
+  expect(transformedContent).toContain('](/docs/1.0.0/doc2');
+  expect(transformedContent).not.toContain('](../doc2.md)');
+  expect(content).not.toEqual(transformedContent);
+});

packages/docusaurus-plugin-content-docs/src/markdown/index.ts

@@ -11,7 +11,7 @@ import linkify from './linkify';
 
 export = function(fileString: string) {
   const callback = this.async();
-  const {docsDir, siteDir, sourceToPermalink} = getOptions(this);
+  const {docsDir, siteDir, versionedDir, sourceToPermalink} = getOptions(this);
   return (
     callback &&
     callback(
@@ -22,6 +22,7 @@ export = function(fileString: string) {
         docsDir,
         siteDir,
         sourceToPermalink,
+        versionedDir,
       ),
     )
   );

packages/docusaurus-plugin-content-docs/src/markdown/linkify.ts

@@ -7,6 +7,7 @@
 
 import path from 'path';
 import {resolve} from 'url';
+import {getSubFolder} from '@docusaurus/utils';
 import {SourceToPermalink} from '../types';
 
 export default function(
@@ -15,12 +16,19 @@ export default function(
   docsDir: string,
   siteDir: string,
   sourceToPermalink: SourceToPermalink,
+  versionedDir?: string,
 ) {
   // Determine the source dir. e.g: /website/docs, /website/versioned_docs/version-1.0.0
   let sourceDir: string | undefined;
   const thisSource = filePath;
   if (thisSource.startsWith(docsDir)) {
     sourceDir = docsDir;
+  } else if (versionedDir && thisSource.startsWith(versionedDir)) {
+    const specificVersionDir = getSubFolder(thisSource, versionedDir);
+    // e.g: specificVersionDir = version-1.0.0
+    if (specificVersionDir) {
+      sourceDir = path.join(versionedDir, specificVersionDir);
+    }
   }
 
   let content = fileString;