refactor: use markdown dialects (gfm as default)

.changeset/3157.md

@@ -1,15 +1,16 @@
 ---
-'@backstage/core': minor
+'@backstage/core': patch
 ---
 
-Adds the MarkdownContent component to render and display markdown input.
+Adds the MarkdownContent component to render and display Markdown content with the default
+[GFM](https://github.github.com/gfm/) (Github flavored Markdown) dialect.
 
 ```
-  <MarkdownContent content={markdown} />
+<MarkdownContent content={markdownGithubFlavored} />
 ```
 
-Render and display the github flavored markdown [GFM](https://github.github.com/gfm/) input:
+To render the Markdown content with plain [CommonMark](https://commonmark.org/), set the dialect to `common-mark`
 
 ```
- <MarkdownContent content={markdownGithubFlavored} enableGfm />
+<MarkdownContent content={markdown} dialect='common-mark />
 ```

packages/core/src/components/MarkdownContent/MarkdownContent.stories.tsx

@@ -112,9 +112,9 @@ const markdown =
   'Pedis hic, est bis quod, adhaeret et reditum. Fixa sic vel pugnare **forte est**\n' +
   'parte in quaerite generisque repugnat; de quod, creatos.';
 export const MarkdownContentCommonMark = () => (
-  <MarkdownContent content={markdown} />
+  <MarkdownContent content={markdown} dialect="common-mark" />
 );
 
 export const MarkdownContentGithubFlavoredCommonMark = () => (
-  <MarkdownContent content={markdownGithubFlavored} enableGfm />
+  <MarkdownContent content={markdownGithubFlavored} dialect="gfm" />
 );

packages/core/src/components/MarkdownContent/MarkdownContent.test.tsx

@@ -19,7 +19,7 @@ import { renderWithEffects, wrapInTestApp } from '@backstage/test-utils';
 import { MarkdownContent } from './MarkdownContent';
 
 describe('<MarkdownContent />', () => {
-  it('render MarkdownContent component with common mark', async () => {
+  it('render MarkdownContent component', async () => {
     const rendered = await renderWithEffects(
       wrapInTestApp(
         <MarkdownContent content={'# H1\n' + '## H2\n' + '### H3'} />,
@@ -30,17 +30,26 @@ describe('<MarkdownContent />', () => {
     expect(rendered.getByText('H3', { selector: 'h3' })).toBeInTheDocument();
   });
 
-  it('render MarkdownContent component with common mark github flavored', async () => {
+  it('render MarkdownContent component with GitHub flavored Markdown dialect', async () => {
     const rendered = await renderWithEffects(
-      wrapInTestApp(
-        <MarkdownContent content="https://example.com" enableGfm />,
-      ),
+      wrapInTestApp(<MarkdownContent content="https://example.com" />),
     );
     expect(
       rendered.getByText('https://example.com', { selector: 'a' }),
     ).toBeInTheDocument();
   });
 
+  it('Render MarkdownContent component with common mark dialect', async () => {
+    const rendered = await renderWithEffects(
+      wrapInTestApp(
+        <MarkdownContent content="https://example.com" dialect="common-mark" />,
+      ),
+    );
+    expect(
+      rendered.getByText('https://example.com', { selector: 'p' }),
+    ).toBeInTheDocument();
+  });
+
   it('render MarkdownContent component with CodeSnippet for code blocks', async () => {
     const rendered = await renderWithEffects(
       wrapInTestApp(<MarkdownContent content="    jest(test: string);" />),

packages/core/src/components/MarkdownContent/MarkdownContent.tsx

@@ -59,12 +59,9 @@ const useStyles = makeStyles<BackstageTheme>(theme => ({
   },
 }));
 
-/**
- * MarkdownContent. Renders markdown (CommonMark, optionally with [GFM](https://github.com/remarkjs/remark-gfm)) to formatted HTML.
- */
 type Props = {
   content: string;
-  enableGfm?: boolean;
+  dialect?: 'gfm' | 'common-mark';
 };
 
 const renderers = {
@@ -73,11 +70,17 @@ const renderers = {
   },
 };
 
-export const MarkdownContent = ({ content, enableGfm = false }: Props) => {
+/**
+ * MarkdownContent
+ * --
+ * Renders markdown with the default dialect [gfm - GitHub flavored Markdown](https://github.github.com/gfm/) to backstage theme styled HTML.
+ * If you just want to render to plain [CommonMark](https://commonmark.org/), set the dialect to `'common-mark'`
+ */
+export const MarkdownContent = ({ content, dialect = 'gfm' }: Props) => {
   const classes = useStyles();
   return (
     <ReactMarkdown
-      plugins={enableGfm ? [gfm] : []}
+      plugins={dialect === 'gfm' ? [gfm] : []}
       className={classes.markdown}
       children={content}
       renderers={renderers}