feat(content-docs): sidebar category linking to document or auto-generated index page (#5830)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: Armano <armano2@users.noreply.github.com>
Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>

packages/docusaurus-utils/package.json

@@ -23,6 +23,7 @@
     "chalk": "^4.1.2",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^10.0.0",
+    "github-slugger": "^1.4.0",
     "globby": "^11.0.4",
     "gray-matter": "^4.0.3",
     "lodash": "^4.17.20",
@@ -37,6 +38,7 @@
   },
   "devDependencies": {
     "@types/dedent": "^0.7.0",
+    "@types/github-slugger": "^1.3.0",
     "@types/micromatch": "^4.0.2",
     "@types/react-dom": "^17.0.1",
     "dedent": "^0.7.0"

packages/docusaurus-utils/src/__tests__/slugger.test.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {createSlugger} from '../slugger';
+
+describe('createSlugger', () => {
+  test('can create unique slugs', () => {
+    const slugger = createSlugger();
+    expect(slugger.slug('Some$/vaLue$!^')).toEqual('somevalue');
+    expect(slugger.slug('Some$/vaLue$!^')).toEqual('somevalue-1');
+    expect(slugger.slug('Some$/vaLue$!^')).toEqual('somevalue-2');
+    expect(slugger.slug('Some$/vaLue$!^-1')).toEqual('somevalue-1-1');
+  });
+
+  test('can create unique slugs respecting case', () => {
+    const slugger = createSlugger();
+    const opt = {maintainCase: true};
+    expect(slugger.slug('Some$/vaLue$!^', opt)).toEqual('SomevaLue');
+    expect(slugger.slug('Some$/vaLue$!^', opt)).toEqual('SomevaLue-1');
+    expect(slugger.slug('Some$/vaLue$!^', opt)).toEqual('SomevaLue-2');
+    expect(slugger.slug('Some$/vaLue$!^-1', opt)).toEqual('SomevaLue-1-1');
+  });
+});

packages/docusaurus-utils/src/index.ts

@@ -33,6 +33,7 @@ export const posixPath = posixPathImport;
 export * from './markdownParser';
 export * from './markdownLinks';
 export * from './escapePath';
+export * from './slugger';
 export {md5Hash, simpleHash, docuHash} from './hashUtils';
 export {
   Globby,

packages/docusaurus-utils/src/slugger.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import GithubSlugger from 'github-slugger';
+
+// We create our own abstraction on top of the lib:
+// - unify usage everywhere in the codebase
+// - ability to add extra options
+export type SluggerOptions = {maintainCase?: boolean};
+
+export type Slugger = {
+  slug: (value: string, options?: SluggerOptions) => string;
+};
+
+export function createSlugger(): Slugger {
+  const githubSlugger = new GithubSlugger();
+  return {
+    slug: (value, options) => githubSlugger.slug(value, options?.maintainCase),
+  };
+}