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"