fix(v2): remove Markdown syntax from excerpt

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

@@ -298,7 +298,7 @@ describe('versioned website', () => {
       permalink: '/docs/next/foo/bar',
       source: path.join('@site', routeBasePath, 'foo', 'bar.md'),
       title: 'bar',
-      description: 'This is `next` version of bar.',
+      description: 'This is next version of bar.',
       version: 'next',
       sidebar: 'docs',
       next: {
@@ -311,7 +311,7 @@ describe('versioned website', () => {
       permalink: '/docs/next/hello',
       source: path.join('@site', routeBasePath, 'hello.md'),
       title: 'hello',
-      description: 'Hello `next` !',
+      description: 'Hello next !',
       version: 'next',
       sidebar: 'docs',
       previous: {
@@ -329,7 +329,7 @@ describe('versioned website', () => {
         'hello.md',
       ),
       title: 'hello',
-      description: 'Hello `1.0.1` !',
+      description: 'Hello 1.0.1 !',
       version: '1.0.1',
       sidebar: 'version-1.0.1/docs',
       previous: {
@@ -349,7 +349,7 @@ describe('versioned website', () => {
       ),
       title: 'baz',
       description:
-        'Baz `1.0.0` ! This will be deleted in next subsequent versions.',
+        'Baz 1.0.0 ! This will be deleted in next subsequent versions.',
       version: '1.0.0',
       sidebar: 'version-1.0.0/docs',
       next: {

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

@@ -84,7 +84,7 @@ describe('simple site', () => {
       title: 'baz',
       editUrl:
         'https://github.com/facebook/docusaurus/edit/master/website/docs/foo/baz.md',
-      description: '## Images',
+      description: 'Images',
     });
   });
 
@@ -228,15 +228,15 @@ describe('versioned site', () => {
       permalink: '/docs/next/foo/bar',
       source: path.join('@site', routeBasePath, sourceA),
       title: 'bar',
-      description: 'This is `next` version of bar.',
+      description: 'This is next version of bar.',
       version: 'next',
     });
     expect(dataB).toEqual({
       id: 'hello',
       permalink: '/docs/next/hello',
       source: path.join('@site', routeBasePath, sourceB),
       title: 'hello',
-      description: 'Hello `next` !',
+      description: 'Hello next !',
       version: 'next',
     });
   });
@@ -286,31 +286,31 @@ describe('versioned site', () => {
       permalink: '/docs/1.0.0/foo/bar',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceA),
       title: 'bar',
-      description: 'Bar `1.0.0` !',
+      description: 'Bar 1.0.0 !',
       version: '1.0.0',
     });
     expect(dataB).toEqual({
       id: 'version-1.0.0/hello',
       permalink: '/docs/1.0.0/hello',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceB),
       title: 'hello',
-      description: 'Hello `1.0.0` !',
+      description: 'Hello 1.0.0 !',
       version: '1.0.0',
     });
     expect(dataC).toEqual({
       id: 'version-1.0.1/foo/bar',
       permalink: '/docs/foo/bar',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceC),
       title: 'bar',
-      description: 'Bar `1.0.1` !',
+      description: 'Bar 1.0.1 !',
       version: '1.0.1',
     });
     expect(dataD).toEqual({
       id: 'version-1.0.1/hello',
       permalink: '/docs/hello',
       source: path.join('@site', path.relative(siteDir, versionedDir), sourceD),
       title: 'hello',
-      description: 'Hello `1.0.1` !',
+      description: 'Hello 1.0.1 !',
       version: '1.0.1',
     });
   });

packages/docusaurus-utils/package.json

@@ -12,11 +12,15 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@types/remove-markdown": "^0.1.1",
     "escape-string-regexp": "^2.0.0",
     "fs-extra": "^8.1.0",
     "gray-matter": "^4.0.2",
     "lodash.camelcase": "^4.3.0",
-    "lodash.kebabcase": "^4.1.1"
+    "lodash.kebabcase": "^4.1.1",
+    "remark": "^12.0.0",
+    "remove-markdown": "^0.3.0",
+    "strip-markdown": "^3.1.2"
   },
   "engines": {
     "node": ">=10.9.0"

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

@@ -17,6 +17,7 @@ import {
   posixPath,
   objectWithKeySorted,
   aliasedSitePath,
+  createExcerpt,
 } from '../index';
 
 describe('load utils', () => {
@@ -292,4 +293,60 @@ describe('load utils', () => {
       `"Url must be a string. Received undefined"`,
     );
   });
+
+  test('createExcerpt', () => {
+    const asserts = [
+      // Regular content
+      {
+        input: `
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ex urna, molestie et sagittis ut, varius ac justo.
+
+          Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis.
+        `,
+        output:
+          'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ex urna, molestie et sagittis ut, varius ac justo.',
+      },
+      // Content with imports declarations and Markdown markup, as well as Emoji
+      {
+        input: `
+          import Component from '@site/src/components/Component';
+          import Component from '@site/src/components/Component'
+
+          Lorem **ipsum** dolor sit \`amet\`, consectetur _adipiscing_ elit. [**Vestibulum**](#) ex urna, molestie et sagittis ut, varius ac justo :wink:.
+
+          Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis.
+        `,
+        output:
+          'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ex urna, molestie et sagittis ut, varius ac justo.',
+      },
+      // Content beginning with admonitions
+      {
+        input: `
+          import Component from '@site/src/components/Component'
+
+          :::caution
+
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+          :::
+
+          Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis.
+        `,
+        output: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
+      },
+      // Content beginning with heading
+      {
+        input: `
+          # Lorem ipsum dolor sit amet
+
+          Nunc porttitor libero nec vulputate venenatis. Nam nec rhoncus mauris. Morbi tempus est et nibh maximus, tempus venenatis arcu lobortis.
+        `,
+        output: 'Lorem ipsum dolor sit amet',
+      },
+    ];
+
+    asserts.forEach((testCase) => {
+      expect(createExcerpt(testCase.input)).toEqual(testCase.output);
+    });
+  });
 });

packages/docusaurus-utils/src/index.ts

@@ -12,6 +12,9 @@ import camelCase from 'lodash.camelcase';
 import kebabCase from 'lodash.kebabcase';
 import escapeStringRegexp from 'escape-string-regexp';
 import fs from 'fs-extra';
+// import removeMd from 'remove-markdown';
+import remark from 'remark';
+import strip from 'strip-markdown';
 
 const fileHash = new Map();
 export async function generate(
@@ -185,6 +188,37 @@ export function getSubFolder(file: string, refDir: string): string | null {
 // Regex for an import statement.
 const importRegexString = '^(.*import){1}(.+){0,1}\\s[\'"](.+)[\'"];?';
 
+function removeMd(markdownString: string): string {
+  return remark().use(strip).processSync(markdownString.trim()).toString();
+}
+
+export function createExcerpt(fileString: string): string | undefined {
+  let fileContent = fileString.trimLeft();
+
+  if (RegExp(importRegexString).test(fileContent)) {
+    fileContent = fileContent
+      .replace(RegExp(importRegexString, 'gm'), '')
+      .trimLeft();
+  }
+
+  const fileLines = fileContent.split('\n');
+
+  for (let fileLine of fileLines) {
+    const cleanedLine = removeMd(fileLine)
+      // Remove definition of admonition.
+      .replace(/(:{3}.*)/, '')
+      // Remove Emoji names within colons include preceding whitespace.
+      .replace(/\s?(:(::|[^:\n])+:)/g, '')
+      .trim();
+
+    if (cleanedLine) {
+      return cleanedLine;
+    }
+  }
+
+  return undefined;
+}
+
 export function parse(
   fileString: string,
 ): {
@@ -196,18 +230,10 @@ export function parse(
 } {
   const options: {} = {
     excerpt: (file: matter.GrayMatterFile<string>): void => {
-      let fileContent = file.content.trimLeft();
-
       // Hacky way of stripping out import statements from the excerpt
       // TODO: Find a better way to do so, possibly by compiling the Markdown content,
       // stripping out HTML tags and obtaining the first line.
-      if (RegExp(importRegexString).test(fileContent)) {
-        fileContent = fileContent
-          .replace(RegExp(importRegexString, 'gm'), '')
-          .trimLeft();
-      }
-
-      file.excerpt = fileContent.split('\n', 1).shift();
+      file.excerpt = createExcerpt(file.content);
     },
   };
 

packages/docusaurus-utils/types.d.ts

@@ -0,0 +1 @@
+declare module 'strip-markdown';

yarn.lock

@@ -2725,6 +2725,11 @@
   resolved "https://registry.yarnpkg.com/@types/relateurl/-/relateurl-0.2.28.tgz#6bda7db8653fa62643f5ee69e9f69c11a392e3a6"
   integrity sha1-a9p9uGU/piZD9e5p6facEaOS46Y=
 
+"@types/remove-markdown@^0.1.1":
+  version "0.1.1"
+  resolved "https://registry.yarnpkg.com/@types/remove-markdown/-/remove-markdown-0.1.1.tgz#c79d3000df412526186b2af3808b85bee68bc907"
+  integrity sha512-SCYOFMHUqyiJU5M0V2gBB6UDdBhPwma34j0vYX0JgWaqp/74ila2Ops1jt5tB/C1UQXVXqK+is61884bITn3LQ==
+
 "@types/semver@^7.1.0":
   version "7.1.0"
   resolved "https://registry.yarnpkg.com/@types/semver/-/semver-7.1.0.tgz#c8c630d4c18cd326beff77404887596f96408408"
@@ -14559,6 +14564,11 @@ remarkable@^2.0.0:
     argparse "^1.0.10"
     autolinker "^3.11.0"
 
+remove-markdown@^0.3.0:
+  version "0.3.0"
+  resolved "https://registry.yarnpkg.com/remove-markdown/-/remove-markdown-0.3.0.tgz#5e4b667493a93579728f3d52ecc1db9ca505dc98"
+  integrity sha1-XktmdJOpNXlyjz1S7MHbnKUF3Jg=
+
 remove-trailing-separator@^1.0.1:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/remove-trailing-separator/-/remove-trailing-separator-1.1.0.tgz#c24bce2a283adad5bc3f58e0d48249b92379d8ef"
@@ -15897,6 +15907,11 @@ strip-json-comments@~2.0.1:
   resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-2.0.1.tgz#3c531942e908c2697c0ec344858c286c7ca0a60a"
   integrity sha1-PFMZQukIwml8DsNEhYwobHygpgo=
 
+strip-markdown@^3.1.2:
+  version "3.1.2"
+  resolved "https://registry.yarnpkg.com/strip-markdown/-/strip-markdown-3.1.2.tgz#172f6f89f9a98896e65a65422e0507f2bbac1667"
+  integrity sha512-NjwW6CEefesmHQPs7lof/lgnSriqUnRNOWpnrNPq9A7/yOCdnhaB7DcxlhYuN7WiiRUe349aitAsTQ/ajM9Dmw==
+
 strip-outer@^1.0.0:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/strip-outer/-/strip-outer-1.0.1.tgz#b2fd2abf6604b9d1e6013057195df836b8a9d631"