@mui/internal-markdown 1.0.0

package/prepareMarkdown.test.js

@@ -0,0 +1,417 @@
+import { expect } from 'chai';
+import prepareMarkdown from './prepareMarkdown';
+
+describe('prepareMarkdown', () => {
+  const defaultParams = {
+    fileRelativeContext: 'test/bar',
+    options: {
+      env: {},
+    },
+  };
+
+  it('returns the table of contents with html and emojis preserved and <a> tags stripped', () => {
+    const markdown = `
+# Support
+
+<p class="description">Foo</p>
+
+## Community help (free)
+### GitHub <img src="/static/images/logos/github.svg" width="24" height="24" alt="GitHub logo" loading="lazy" />
+### Unofficial 👍
+### Warning ⚠️
+### Header with Pro plan <a title="Pro plan" href="/x/introduction/licensing/#plan-pro"><span class="plan-pro"></span></a>
+### Header with \`code\`
+`;
+
+    const {
+      docs: {
+        en: { toc },
+      },
+    } = prepareMarkdown({
+      ...defaultParams,
+      translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+    });
+
+    expect(toc).to.have.deep.ordered.members([
+      {
+        children: [
+          {
+            hash: 'github',
+            level: 3,
+            text: 'GitHub <img src="/static/images/logos/github.svg" width="24" height="24" alt="GitHub logo" loading="lazy" />',
+          },
+          { hash: 'unofficial', level: 3, text: 'Unofficial 👍' },
+          { hash: 'warning', level: 3, text: 'Warning ⚠️' },
+          {
+            hash: 'header-with-pro-plan',
+            level: 3,
+            text: 'Header with Pro plan <span class="plan-pro"></span>',
+          },
+          {
+            hash: 'header-with-code',
+            level: 3,
+            text: 'Header with code',
+          },
+        ],
+        hash: 'community-help-free',
+        level: 2,
+        text: 'Community help (free)',
+      },
+    ]);
+  });
+
+  it('enables word-break for function signatures', () => {
+    const markdown = `
+# Theming
+
+<p class="description">Foo</p>
+
+## API
+### responsiveFontSizes(theme, options) => theme
+### createTheme(options, ...args) => theme
+`;
+
+    const {
+      docs: {
+        en: { toc },
+      },
+    } = prepareMarkdown({
+      ...defaultParams,
+      translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+    });
+
+    expect(toc).to.have.deep.ordered.members([
+      {
+        children: [
+          {
+            hash: 'responsivefontsizes-theme-options-theme',
+            level: 3,
+            text: 'responsiveFontSizes(&#8203;theme, options) =&gt; theme',
+          },
+          {
+            hash: 'createtheme-options-args-theme',
+            level: 3,
+            text: 'createTheme(&#8203;options, ...args) =&gt; theme',
+          },
+        ],
+        hash: 'api',
+        level: 2,
+        text: 'API',
+      },
+    ]);
+  });
+
+  it('use english hash for different locales', () => {
+    const markdownEn = `
+# Localization
+
+<p class="description">Foo</p>
+
+## Locales
+### Example
+### Use same hash
+`;
+
+    const markdownPt = `
+# Localização
+
+<p class="description">Foo</p>
+
+## Idiomas
+### Exemplo
+### Usar o mesmo hash
+`;
+
+    const markdownZh = `
+# 所在位置
+
+<p class="description">Foo</p>
+
+## 语言环境
+### 例
+### 使用相同的哈希
+`;
+    const {
+      docs: {
+        en: { toc: tocEn },
+        pt: { toc: tocPt },
+        zh: { toc: tocZh },
+      },
+    } = prepareMarkdown({
+      pageFilename: '/same-hash-test',
+      translations: [
+        { filename: 'localization.md', markdown: markdownEn, userLanguage: 'en' },
+        { filename: 'localization-pt.md', markdown: markdownPt, userLanguage: 'pt' },
+        { filename: 'localization-zh.md', markdown: markdownZh, userLanguage: 'zh' },
+      ],
+    });
+
+    expect(tocZh).to.have.deep.ordered.members([
+      {
+        children: [
+          {
+            hash: 'example',
+            level: 3,
+            text: '例',
+          },
+          {
+            hash: 'use-same-hash',
+            level: 3,
+            text: '使用相同的哈希',
+          },
+        ],
+        hash: 'locales',
+        level: 2,
+        text: '语言环境',
+      },
+    ]);
+
+    expect(tocPt).to.have.deep.ordered.members([
+      {
+        children: [
+          {
+            hash: 'example',
+            level: 3,
+            text: 'Exemplo',
+          },
+          {
+            hash: 'use-same-hash',
+            level: 3,
+            text: 'Usar o mesmo hash',
+          },
+        ],
+        hash: 'locales',
+        level: 2,
+        text: 'Idiomas',
+      },
+    ]);
+
+    expect(tocEn).to.have.deep.ordered.members([
+      {
+        children: [
+          {
+            hash: 'example',
+            level: 3,
+            text: 'Example',
+          },
+          {
+            hash: 'use-same-hash',
+            level: 3,
+            text: 'Use same hash',
+          },
+        ],
+        hash: 'locales',
+        level: 2,
+        text: 'Locales',
+      },
+    ]);
+  });
+
+  it('use translated hash for translations are not synced', () => {
+    const markdownEn = `
+# Localization
+
+<p class="description">Foo</p>
+
+## Locales
+### Example
+### Use same hash
+`;
+
+    const markdownPt = `
+# Localização
+
+<p class="description">Foo</p>
+
+## Idiomas
+### Exemplo
+### Usar o mesmo hash
+### Usar traduzido
+`;
+
+    const {
+      docs: {
+        en: { toc: tocEn },
+        pt: { toc: tocPt },
+      },
+    } = prepareMarkdown({
+      pageFilename: '/same-hash-test',
+      translations: [
+        { filename: 'localization.md', markdown: markdownEn, userLanguage: 'en' },
+        { filename: 'localization-pt.md', markdown: markdownPt, userLanguage: 'pt' },
+      ],
+    });
+
+    expect(tocPt).to.have.deep.ordered.members([
+      {
+        children: [
+          {
+            hash: 'example',
+            level: 3,
+            text: 'Exemplo',
+          },
+          {
+            hash: 'use-same-hash',
+            level: 3,
+            text: 'Usar o mesmo hash',
+          },
+          {
+            hash: 'usar-traduzido',
+            level: 3,
+            text: 'Usar traduzido',
+          },
+        ],
+        hash: 'locales',
+        level: 2,
+        text: 'Idiomas',
+      },
+    ]);
+
+    expect(tocEn).to.have.deep.ordered.members([
+      {
+        children: [
+          {
+            hash: 'example',
+            level: 3,
+            text: 'Example',
+          },
+          {
+            hash: 'use-same-hash',
+            level: 3,
+            text: 'Use same hash',
+          },
+        ],
+        hash: 'locales',
+        level: 2,
+        text: 'Locales',
+      },
+    ]);
+  });
+
+  it('should report missing trailing splashes', () => {
+    const markdown = `
+# Localization
+
+<p class="description">Foo</p>
+
+[bar](/bar/)
+[foo](/foo)
+`;
+
+    expect(() => {
+      prepareMarkdown({
+        ...defaultParams,
+        translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+      });
+    }).to.throw(`docs-infra: Missing trailing slash. The following link:
+[foo](/foo) in /test/bar/index.md is missing a trailing slash, please add it.
+
+See https://ahrefs.com/blog/trailing-slash/ for more details.
+`);
+  });
+
+  it('should report missing leading splashes', () => {
+    const markdown = `
+# Localization
+
+<p class="description">Foo</p>
+
+[bar](/bar/)
+[foo](foo/)
+`;
+
+    expect(() => {
+      prepareMarkdown({
+        ...defaultParams,
+        translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+      });
+    }).to.throw(`docs-infra: Missing leading slash. The following link:
+[foo](foo/) in /test/bar/index.md is missing a leading slash, please add it.
+`);
+  });
+
+  it('should report title too long', () => {
+    const markdown = `
+# Foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
+
+<p class="description">Foo</p>
+
+`;
+
+    expect(() => {
+      prepareMarkdown({
+        ...defaultParams,
+        translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+      });
+    }).to
+      .throw(`docs-infra: The title "Foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo" is too long (117 characters).
+It needs to have fewer than 70 characters—ideally less than 60. For more details, see:
+https://developers.google.com/search/docs/advanced/appearance/title-link
+`);
+  });
+
+  it('should report description too long', () => {
+    const markdown = `
+# Foo
+
+<p class="description">Fooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo</p>
+
+`;
+
+    expect(() => {
+      prepareMarkdown({
+        ...defaultParams,
+        translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+      });
+    }).to
+      .throw(`docs-infra: The description "Fooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo" is too long (188 characters).
+It needs to have fewer than 170 characters—ideally less than 160. For more details, see:
+https://ahrefs.com/blog/meta-description/#4-be-concise
+`);
+  });
+
+  it('should not accept sh', () => {
+    const markdown = `
+# Foo
+
+<p class="description">Fo</p>
+
+\`\`\`sh
+npm install @mui/material
+\`\`\`
+
+`;
+
+    expect(() => {
+      prepareMarkdown({
+        ...defaultParams,
+        translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+      });
+    }).to.throw(`docs-infra: Unsupported language: "sh" in:
+
+\`\`\`sh
+npm install @mui/material
+\`\`\`
+
+Use "bash" instead.
+`);
+  });
+
+  it('should report duplicated trailing splashes', () => {
+    const markdown = `
+# Localization
+
+<p class="description">Foo</p>
+
+[foo](/foo/)
+[bar](/bar//#foo)
+`;
+
+    expect(() => {
+      prepareMarkdown({
+        ...defaultParams,
+        translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
+      });
+    }).to.throw(`docs-infra: Duplicated trailing slashes.`);
+  });
+});

package/prism.d.ts

@@ -0,0 +1 @@
+export default function highlight(code: string, language: string): string;

package/prism.js

@@ -0,0 +1,61 @@
+const prism = require('prismjs');
+require('prismjs/components/prism-css');
+require('prismjs/components/prism-bash');
+require('prismjs/components/prism-diff');
+require('prismjs/components/prism-javascript');
+require('prismjs/components/prism-json');
+require('prismjs/components/prism-jsx');
+require('prismjs/components/prism-markup');
+require('prismjs/components/prism-yaml');
+require('prismjs/components/prism-tsx');
+
+function highlight(code, language) {
+  let prismLanguage;
+  switch (language) {
+    case 'ts':
+      prismLanguage = prism.languages.tsx;
+      break;
+
+    case 'js':
+      prismLanguage = prism.languages.jsx;
+      break;
+
+    case 'sh':
+      throw new Error(
+        [
+          `docs-infra: Unsupported language: "sh" in:`,
+          '',
+          '```sh',
+          code,
+          '```',
+          '',
+          'Use "bash" instead.',
+          '',
+        ].join('\n'),
+      );
+
+    case 'diff':
+      prismLanguage = { ...prism.languages.diff };
+      // original `/^[-<].*$/m` matches lines starting with `<` which matches
+      // <SomeComponent />
+      // we will only use `-` as the deleted marker
+      prismLanguage.deleted = /^[-].*$/m;
+      break;
+
+    default:
+      prismLanguage = prism.languages[language];
+      break;
+  }
+
+  if (!prismLanguage) {
+    if (language) {
+      throw new Error(`unsupported language: "${language}", "${code}"`);
+    } else {
+      prismLanguage = prism.languages.jsx;
+    }
+  }
+
+  return prism.highlight(code, prismLanguage);
+}
+
+module.exports = highlight;

package/textToHash.js

@@ -0,0 +1,36 @@
+function makeUnique(hash, unique, i = 1) {
+  const uniqueHash = i === 1 ? hash : `${hash}-${i}`;
+
+  if (!unique[uniqueHash]) {
+    unique[uniqueHash] = true;
+    return uniqueHash;
+  }
+
+  return makeUnique(hash, unique, i + 1);
+}
+
+/**
+ * @param {string} text - HTML from e.g. parseMarkdown#render
+ * @param {Record<string, boolean>} [unique] - Ensures that each output is unique in `unique`
+ * @returns {string} that is safe to use in fragment links
+ */
+function textToHash(text, unique = {}) {
+  return makeUnique(
+    encodeURI(
+      text
+        .toLowerCase()
+        .replace(/<\/?[^>]+(>|$)/g, '') // remove HTML
+        .replace(/=&gt;|&lt;| \/&gt;|<code>|<\/code>|&#39;/g, '')
+        .replace(/[!@#$%^&*()=_+[\]{}`~;:'"|,.<>/?\s]+/g, '-')
+        .replace(
+          /([\uE000-\uF8FF]|\uD83C[\uDC00-\uDFFF]|\uD83D[\uDC00-\uDFFF]|[\u2011-\u26FF]|\uD83E[\uDD10-\uDDFF])\uFE0F?/g,
+          '',
+        ) // remove emojis
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, ''),
+    ),
+    unique,
+  );
+}
+
+module.exports = textToHash;

package/textToHash.test.js

@@ -0,0 +1,32 @@
+import { expect } from 'chai';
+import { parseInline as renderInlineMarkdown } from 'marked';
+import textToHash from './textToHash';
+
+describe('textToHash', () => {
+  it('should hash as expected', () => {
+    const table = [
+      ['createTheme(options) => theme', 'createtheme-options-theme'],
+      ['Typography - Font family', 'typography-font-family'],
+      ["barre d'application", 'barre-dapplication'],
+      [
+        'createGenerateClassName([options]) => class name generator',
+        'creategenerateclassname-options-class-name-generator',
+      ],
+      ['@mui/material/styles vs @mui/styles', 'mui-material-styles-vs-mui-styles'],
+      ['Blog 📝', 'blog'],
+    ];
+    table.forEach((entry, index) => {
+      const [markdown, expected] = entry;
+      const text = renderInlineMarkdown(markdown, { mangle: false, headerIds: false });
+      const actual = textToHash(text);
+
+      expect(actual).to.equal(expected, `snapshot #${index} matches`);
+    });
+  });
+
+  it('should generate a unique hash', () => {
+    const unique = {};
+    expect(textToHash('Styling solution', unique)).to.equal('styling-solution');
+    expect(textToHash('Styling solution', unique)).to.equal('styling-solution-2');
+  });
+});