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/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**](https://wiktionary.org/wiki/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

@@ -185,6 +185,49 @@ export function getSubFolder(file: string, refDir: string): string | null {
 // Regex for an import statement.
 const importRegexString = '^(.*import){1}(.+){0,1}\\s[\'"](.+)[\'"];?';
 
+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 = fileLine
+      // Remove HTML tags.
+      .replace(/<[^>]*>/g, '')
+      // Remove ATX-style headers.
+      .replace(/^\#{1,6}\s*([^#]*)\s*(\#{1,6})?/gm, '$1')
+      // Remove emphasis and strikethroughs.
+      .replace(/([\*_~]{1,3})(\S.*?\S{0,1})\1/g, '$2')
+      // Remove inline links.
+      .replace(/\[(.*?)\][\[\(].*?[\]\)]/g, '$1')
+      // Remove inline code.
+      .replace(/`(.+?)`/g, '$1')
+      // Remove images.
+      .replace(/\!\[(.*?)\][\[\(].*?[\]\)]/g, '')
+      // Remove blockquotes.
+      .replace(/^\s{0,3}>\s?/g, '')
+      // Remove footnotes.
+      .replace(/\[\^.+?\](\: .*?$)?/g, '')
+      // Remove admonition definition.
+      .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 +239,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);
     },
   };