feat(v2): add ability to set custom heading id (#4222)

* feat(v2): add ability to set custom heading id

* Add cli command

* Fix slugger

* write-heading-ids doc + add in commands/templates

* refactor + add tests for writeHeadingIds

* polish writeHeadingIds

* polish writeHeadingIds

* remove i18n goals todo section as the  remaining items are quite abstract/useless

* fix edge case with 2 md links in heading

* extract parseMarkdownHeadingId helper function

* refactor using the shared parseMarkdownHeadingId utility fn

* change logic of edge case

* Handle edge case

* Document explicit ids feature

Co-authored-by: slorber <lorber.sebastien@gmail.com>

packages/docusaurus-utils/package.json

@@ -19,6 +19,7 @@
   "license": "MIT",
   "dependencies": {
     "@docusaurus/types": "2.0.0-alpha.70",
+    "@types/github-slugger": "^1.3.0",
     "chalk": "^4.1.0",
     "escape-string-regexp": "^4.0.0",
     "fs-extra": "^9.1.0",

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

@@ -35,6 +35,7 @@ import {
   getFolderContainingFile,
   updateTranslationFileMessages,
   readDefaultCodeTranslationMessages,
+  parseMarkdownHeadingId,
 } from '../index';
 import {sum} from 'lodash';
 
@@ -806,3 +807,51 @@ describe('readDefaultCodeTranslationMessages', () => {
     ).resolves.toEqual(await readAsJSON('en.json'));
   });
 });
+
+describe('parseMarkdownHeadingId', () => {
+  test('can parse simple heading without id', () => {
+    expect(parseMarkdownHeadingId('## Some heading')).toEqual({
+      text: '## Some heading',
+      id: undefined,
+    });
+  });
+
+  test('can parse simple heading with id', () => {
+    expect(parseMarkdownHeadingId('## Some heading {#custom-_id}')).toEqual({
+      text: '## Some heading',
+      id: 'custom-_id',
+    });
+  });
+
+  test('can parse heading not ending with the id', () => {
+    expect(parseMarkdownHeadingId('## {#custom-_id} Some heading')).toEqual({
+      text: '## {#custom-_id} Some heading',
+      id: undefined,
+    });
+  });
+
+  test('can parse heading with multiple id', () => {
+    expect(parseMarkdownHeadingId('## Some heading {#id1} {#id2}')).toEqual({
+      text: '## Some heading {#id1}',
+      id: 'id2',
+    });
+  });
+
+  test('can parse heading with link and id', () => {
+    expect(
+      parseMarkdownHeadingId(
+        '## Some heading [facebook](https://facebook.com) {#id}',
+      ),
+    ).toEqual({
+      text: '## Some heading [facebook](https://facebook.com)',
+      id: 'id',
+    });
+  });
+
+  test('can parse heading with only id', () => {
+    expect(parseMarkdownHeadingId('## {#id}')).toEqual({
+      text: '##',
+      id: 'id',
+    });
+  });
+});

packages/docusaurus-utils/src/index.ts

@@ -642,3 +642,23 @@ export function getDateTimeFormat(locale: string) {
     : // eslint-disable-next-line @typescript-eslint/no-var-requires
       require('intl').DateTimeFormat;
 }
+
+// Input: ## Some heading {#some-heading}
+// Output: {text: "## Some heading", id: "some-heading"}
+export function parseMarkdownHeadingId(
+  heading: string,
+): {
+  text: string;
+  id?: string;
+} {
+  const customHeadingIdRegex = /^(.*?)\s*\{#([\w-]+)\}$/;
+  const matches = customHeadingIdRegex.exec(heading);
+  if (matches) {
+    return {
+      text: matches[1],
+      id: matches[2],
+    };
+  } else {
+    return {text: heading, id: undefined};
+  }
+}