[docs-infra] Support rendering markdown outside of docs (mui#37691)

mfal · Jun 24, 2023 · 314c3d4 · 314c3d4
1 parent 35d8bd6
commit 314c3d4
Show file tree

Hide file tree

Showing 7 changed files with 36 additions and 24 deletions.
diff --git a/docs/src/modules/components/AppLayoutDocs.js b/docs/src/modules/components/AppLayoutDocs.js
@@ -135,7 +135,7 @@ function AppLayoutDocs(props) {
           */}
           <StyledAppContainer disableAd={disableAd} hasTabs={hasTabs}>
             <ActionsDiv>
-              <EditPage markdownLocation={location} />
+              <EditPage sourceLocation={location} />
             </ActionsDiv>
             {children}
             <NoSsr>

diff --git a/docs/src/modules/components/AppLayoutDocsWithoutAppFrame.js b/docs/src/modules/components/AppLayoutDocsWithoutAppFrame.js
@@ -77,7 +77,7 @@ const ActionsDiv = styled('div')(({ theme }) => ({
   },
 }));
 
-function AppLayoutDocs(props) {
+function AppLayoutDocsWithoutAppFrame(props) {
   const router = useRouter();
   const {
     children,
@@ -133,7 +133,7 @@ function AppLayoutDocs(props) {
           */}
           <StyledAppContainer disableAd={disableAd} hasTabs={hasTabs}>
             <ActionsDiv>
-              <EditPage markdownLocation={location} />
+              <EditPage sourceLocation={location} />
             </ActionsDiv>
             {children}
             <NoSsr>
@@ -148,7 +148,7 @@ function AppLayoutDocs(props) {
   );
 }
 
-AppLayoutDocs.propTypes = {
+AppLayoutDocsWithoutAppFrame.propTypes = {
   children: PropTypes.node.isRequired,
   description: PropTypes.string.isRequired,
   disableAd: PropTypes.bool.isRequired,
@@ -160,7 +160,7 @@ AppLayoutDocs.propTypes = {
 };
 
 if (process.env.NODE_ENV !== 'production') {
-  AppLayoutDocs.propTypes = exactProp(AppLayoutDocs.propTypes);
+  AppLayoutDocsWithoutAppFrame.propTypes = exactProp(AppLayoutDocsWithoutAppFrame.propTypes);
 }
 
-export default AppLayoutDocs;
+export default AppLayoutDocsWithoutAppFrame;
diff --git a/docs/src/modules/components/EditPage.js b/docs/src/modules/components/EditPage.js
@@ -4,21 +4,22 @@ import Button from '@mui/material/Button';
 import { useUserLanguage, useTranslate } from 'docs/src/modules/utils/i18n';
 import GitHubIcon from '@mui/icons-material/GitHub';
 
+const LOCALES = { zh: 'zh-CN', pt: 'pt-BR', es: 'es-ES' };
+
 export default function EditPage(props) {
-  const { markdownLocation } = props;
+  const { sourceLocation } = props;
   const t = useTranslate();
   const userLanguage = useUserLanguage();
-  const LOCALES = { zh: 'zh-CN', pt: 'pt-BR', es: 'es-ES' };
   const CROWDIN_ROOT_URL = 'https://translate.mui.com/project/material-ui-docs/';
   const crowdInLocale = LOCALES[userLanguage] || userLanguage;
-  const crowdInPath = markdownLocation.substring(0, markdownLocation.lastIndexOf('/'));
+  const crowdInPath = sourceLocation.substring(0, sourceLocation.lastIndexOf('/'));
 
   return (
     <Button
       component="a"
       href={
         userLanguage === 'en'
-          ? `${process.env.SOURCE_CODE_ROOT_URL}${markdownLocation}`
+          ? `${process.env.SOURCE_CODE_ROOT_URL}${sourceLocation}`
           : `${CROWDIN_ROOT_URL}${crowdInLocale}#/${process.env.SOURCE_CODE_ROOT_URL.replace(
               'https://github.com/mui/',
               '',
@@ -52,5 +53,5 @@ export default function EditPage(props) {
 }
 
 EditPage.propTypes = {
-  markdownLocation: PropTypes.string.isRequired,
+  sourceLocation: PropTypes.string.isRequired,
 };
diff --git a/docs/src/modules/components/MarkdownDocsV2.js b/docs/src/modules/components/MarkdownDocsV2.js
@@ -10,7 +10,7 @@ import HooksApiContent from 'docs/src/modules/components/HooksApiContent';
 import { getTranslatedHeader as getComponentTranslatedHeader } from 'docs/src/modules/components/ApiPage';
 import MarkdownElement from 'docs/src/modules/components/MarkdownElementV2';
 import { pathnameToLanguage } from 'docs/src/modules/utils/helpers';
-import AppLayoutDocs from 'docs/src/modules/components/AppLayoutDocsWithoutAppFrame';
+import AppLayoutDocsWithoutAppFrame from 'docs/src/modules/components/AppLayoutDocsWithoutAppFrame';
 import { useTranslate, useUserLanguage } from 'docs/src/modules/utils/i18n';
 import BrandingProvider from 'docs/src/BrandingProvider';
 import Ad from 'docs/src/modules/components/Ad';
@@ -211,7 +211,7 @@ export default function MarkdownDocsV2(props) {
   }
 
   return (
-    <AppLayoutDocs
+    <AppLayoutDocsWithoutAppFrame
       description={description}
       disableAd={disableAd}
       disableToc={disableToc}
@@ -270,7 +270,7 @@ export default function MarkdownDocsV2(props) {
           )}
         </Provider>
       </div>
-    </AppLayoutDocs>
+    </AppLayoutDocsWithoutAppFrame>
   );
 }
 

diff --git a/packages/markdown/loader.js b/packages/markdown/loader.js
@@ -121,12 +121,15 @@ module.exports = async function demoLoader() {
       }),
   );
 
-  const pageFilename = this.context
-    .replace(this.rootContext, '')
+  // Use .. as the docs runs from the /docs folder
+  const repositoryRoot = path.join(this.rootContext, '..');
+  const fileRelativeContext = path
+    .relative(repositoryRoot, this.context)
     // win32 to posix
     .replace(/\\/g, '/');
+
   const { docs } = prepareMarkdown({
-    pageFilename,
+    fileRelativeContext,
     translations,
     componentPackageMapping,
     options,
@@ -157,7 +160,7 @@ module.exports = async function demoLoader() {
       // The import paths currently use a completely different format.
       // They should just use relative imports.
       let moduleID = `./${demoName.replace(
-        `pages/${pageFilename.replace(/^\/src\/pages\//, '')}/`,
+        `pages/${fileRelativeContext.replace(/^docs\/src\/pages\//, '')}/`,
         '',
       )}`;
 

diff --git a/packages/markdown/parseMarkdown.js b/packages/markdown/parseMarkdown.js
@@ -426,11 +426,11 @@ function resolveComponentApiUrl(product, componentPkg, component) {
 /**
  * @param {object} config
  * @param {Array<{ markdown: string, filename: string, userLanguage: string }>} config.translations - Mapping of locale to its markdown
- * @param {string} config.pageFilename - posix filename relative to nextjs pages directory
+ * @param {string} config.fileRelativeContext - posix filename relative to repository root directory
  * @param {object} config.options - provided to the webpack loader
  */
 function prepareMarkdown(config) {
-  const { pageFilename, translations, componentPackageMapping = {}, options } = config;
+  const { fileRelativeContext, translations, componentPackageMapping = {}, options } = config;
 
   const demos = {};
   /**
@@ -446,7 +446,7 @@ function prepareMarkdown(config) {
     .forEach((translation) => {
       const { filename, markdown, userLanguage } = translation;
       const headers = getHeaders(markdown);
-      const location = headers.filename || `/docs${pageFilename}/${filename}`;
+      const location = headers.filename || `/${fileRelativeContext}/${filename}`;
       const title = headers.title || getTitle(markdown);
       const description = headers.description || getDescription(markdown);
 

diff --git a/packages/markdown/parseMarkdown.test.js b/packages/markdown/parseMarkdown.test.js
@@ -9,7 +9,7 @@ import {
 
 describe('parseMarkdown', () => {
   const defaultParams = {
-    pageFilename: '/test',
+    fileRelativeContext: 'test/bar',
     options: {
       env: {},
     },
@@ -439,7 +439,12 @@ authors:
           ...defaultParams,
           translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
         });
-      }).to.throw(/\[foo]\(\/foo\) in \/docs\/test\/index\.md is missing a trailing slash/);
+      }).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.
+
+Please report this to https://github.com/markedjs/marked.`);
     });
 
     it('should report missing leading splashes', () => {
@@ -457,7 +462,10 @@ authors:
           ...defaultParams,
           translations: [{ filename: 'index.md', markdown, userLanguage: 'en' }],
         });
-      }).to.throw(/\[foo]\(foo\/\) in \/docs\/test\/index\.md is missing a leading slash/);
+      }).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.
+
+Please report this to https://github.com/markedjs/marked.`);
     });
 
     it('should report title too long', () => {