fix: relative links being unusable

mui · Mar 16, 2020 · de9b677 · de9b677
1 parent 08cc8c0
commit de9b677
Show file tree

Hide file tree

Showing 16 changed files with 387 additions and 51 deletions.
diff --git a/docs/scripts/buildApi.js b/docs/scripts/buildApi.js
@@ -8,6 +8,8 @@ import path from 'path';
 import kebabCase from 'lodash/kebabCase';
 import uniqBy from 'lodash/uniqBy';
 import { defaultHandlers, parse as docgenParse } from 'react-docgen';
+import remark from 'remark';
+import remarkVisit from 'unist-util-visit';
 import muiDefaultPropsHandler from '../src/modules/utils/defaultPropsHandler';
 import generateMarkdown from '../src/modules/utils/generateMarkdown';
 import { findPagesMarkdown, findComponents } from '../src/modules/utils/find';
@@ -85,7 +87,40 @@ function getInheritance(testInfo, src) {
   };
 }
 
+/**
+ * Produces markdown of the description that can be hosted anywhere.
+ *
+ * By default we assume that the markdown is hosted on material-ui.com which is
+ * why the source includes relative url. We transform them to absolute urls with
+ * this method.
+ *
+ * @param {object} api
+ * @param {object} options
+ */
+function computeApiDescription(api, options) {
+  const { host } = options;
+  return new Promise((resolve, reject) => {
+    remark()
+      .use(function docsLinksAttacher() {
+        return function transformer(tree) {
+          remarkVisit(tree, 'link', linkNode => {
+            if (linkNode.url.startsWith('/')) {
+              linkNode.url = `${host}${linkNode.url}`;
+            }
+          });
+        };
+      })
+      .process(api.description, (error, file) => {
+        if (error) reject(error);
+
+        resolve(file.contents.replace(/\n/g, '\n * '));
+      });
+  });
+}
+
 async function annotateComponentDefinition(component, api) {
+  const HOST = 'https://material-ui.com';
+
   const typesFilename = component.filename.replace(/\.js$/, '.d.ts');
   const typesSource = readFileSync(typesFilename, { encoding: 'utf8' });
   const typesAST = await babel.parseAsync(typesSource, {
@@ -138,26 +173,22 @@ async function annotateComponentDefinition(component, api) {
 
   let inheritanceAPILink = null;
   if (api.inheritance !== null) {
-    const url = api.inheritance.pathname.startsWith('https://')
-      ? api.inheritance.pathname
-      : `https://material-ui.com${rewriteUrlForNextExport(api.inheritance.pathname)}`;
+    const url = api.inheritance.pathname.startsWith('/')
+      ? `${HOST}${rewriteUrlForNextExport(api.inheritance.pathname)}`
+      : api.inheritance.pathname;
 
     inheritanceAPILink = `[${api.inheritance.component} API](${url})`;
   }
 
   const jsdoc = `/**
- * ${api.description.replace(/\n/g, '\n * ')}
- *
+ * ${await computeApiDescription(api, { host: HOST })}
  * Demos:
  * - ${demos
-   .map(
-     page =>
-       `[${pageToTitle(page)}](https://material-ui.com${rewriteUrlForNextExport(page.pathname)})`,
-   )
+   .map(page => `[${pageToTitle(page)}](${HOST}${rewriteUrlForNextExport(page.pathname)})`)
    .join('\n * - ')}
  *
  * API:
- * - [${api.name} API](https://material-ui.com/api/${kebabCase(api.name)}/)
+ * - [${api.name} API](${HOST}/api/${kebabCase(api.name)}/)
  * ${api.inheritance !== null ? `- inherits ${inheritanceAPILink}` : ''}
  */`;
   const typesSourceNew = typesSource.slice(0, start) + jsdoc + typesSource.slice(end);

diff --git a/package.json b/package.json
@@ -127,6 +127,7 @@
     "react": "^16.13.0",
     "react-dom": "^16.13.0",
     "react-test-renderer": "^16.13.0",
+    "remark": "^11.0.2",
     "rimraf": "^3.0.0",
     "rollup": "^1.21.4",
     "rollup-plugin-babel": "^4.3.3",
@@ -141,6 +142,7 @@
     "tslint": "5.14.0",
     "typescript": "^3.8.2",
     "typescript-to-proptypes": "^1.4.0",
+    "unist-util-visit": "^2.0.2",
     "vrtest-mui": "^0.3.3",
     "webpack": "^4.41.0",
     "webpack-cli": "^3.3.9",

diff --git a/packages/material-ui/src/Collapse/Collapse.d.ts b/packages/material-ui/src/Collapse/Collapse.d.ts
@@ -15,7 +15,7 @@ export type CollapseClassKey = 'container' | 'entered' | 'hidden' | 'wrapper' |
 
 /**
  * The Collapse transition is used by the
- * [Vertical Stepper](/components/steppers/#vertical-stepper) StepContent component.
+ * [Vertical Stepper](https://material-ui.com/components/steppers/#vertical-stepper) StepContent component.
  * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.
  *
  * Demos:

diff --git a/packages/material-ui/src/Drawer/Drawer.d.ts b/packages/material-ui/src/Drawer/Drawer.d.ts
@@ -39,7 +39,7 @@ export type DrawerClassKey =
   | 'modal';
 
 /**
- * The props of the [Modal](/api/modal/) component are available
+ * The props of the [Modal](https://material-ui.com/api/modal/) component are available
  * when `variant="temporary"` is set.
  *
  * Demos:

diff --git a/packages/material-ui/src/Fade/Fade.d.ts b/packages/material-ui/src/Fade/Fade.d.ts
@@ -8,7 +8,7 @@ export interface FadeProps extends TransitionProps {
 }
 
 /**
- * The Fade transition is used by the [Modal](/components/modal/) component.
+ * The Fade transition is used by the [Modal](https://material-ui.com/components/modal/) component.
  * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.
  *
  * Demos:

diff --git a/packages/material-ui/src/FormControl/FormControl.d.ts b/packages/material-ui/src/FormControl/FormControl.d.ts
@@ -24,12 +24,12 @@ export interface FormControlTypeMap<P = {}, D extends React.ElementType = 'div'>
  * consistent across the children of the `FormControl`.
  * This context is used by the following components:
  *
- *  - FormLabel
- *  - FormHelperText
- *  - Input
- *  - InputLabel
+ * -   FormLabel
+ * -   FormHelperText
+ * -   Input
+ * -   InputLabel
  *
- * You can find one composition example below and more going to [the demos](/components/text-fields/#components).
+ * You can find one composition example below and more going to [the demos](https://material-ui.com/components/text-fields/#components).
  *
  * ```jsx
  * <FormControl>

diff --git a/packages/material-ui/src/Grow/Grow.d.ts b/packages/material-ui/src/Grow/Grow.d.ts
@@ -10,8 +10,8 @@ export interface GrowProps extends Omit<TransitionProps, 'timeout'> {
 }
 
 /**
- * The Grow transition is used by the [Tooltip](/components/tooltips/) and
- * [Popover](/components/popover/) components.
+ * The Grow transition is used by the [Tooltip](https://material-ui.com/components/tooltips/) and
+ * [Popover](https://material-ui.com/components/popover/) components.
  * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.
  *
  * Demos:

diff --git a/packages/material-ui/src/IconButton/IconButton.d.ts b/packages/material-ui/src/IconButton/IconButton.d.ts
@@ -17,7 +17,7 @@ export type IconButtonTypeMap<
 }>;
 
 /**
- * Refer to the [Icons](/components/icons/) section of the documentation
+ * Refer to the [Icons](https://material-ui.com/components/icons/) section of the documentation
  * regarding the available icon options.
  *
  * Demos:

diff --git a/packages/material-ui/src/MenuList/MenuList.d.ts b/packages/material-ui/src/MenuList/MenuList.d.ts
@@ -12,8 +12,8 @@ export interface MenuListProps extends StandardProps<ListProps, MenuListClassKey
 export type MenuListClassKey = ListClassKey;
 
 /**
- * A permanently displayed menu following https://www.w3.org/TR/wai-aria-practices/#menubutton.
- * It's exposed to help customization of the [`Menu`](/api/menu/) component. If you
+ * A permanently displayed menu following <https://www.w3.org/TR/wai-aria-practices/#menubutton>.
+ * It's exposed to help customization of the [`Menu`](https://material-ui.com/api/menu/) component. If you
  * use it separately you need to move focus into the component manually. Once
  * the focus is placed inside the component it is fully keyboard accessible.
  *

diff --git a/packages/material-ui/src/Modal/Modal.d.ts b/packages/material-ui/src/Modal/Modal.d.ts
@@ -32,12 +32,12 @@ export interface ModalProps
 /**
  * Modal is a lower-level construct that is leveraged by the following components:
  *
- * - [Dialog](/api/dialog/)
- * - [Drawer](/api/drawer/)
- * - [Menu](/api/menu/)
- * - [Popover](/api/popover/)
+ * -   [Dialog](https://material-ui.com/api/dialog/)
+ * -   [Drawer](https://material-ui.com/api/drawer/)
+ * -   [Menu](https://material-ui.com/api/menu/)
+ * -   [Popover](https://material-ui.com/api/popover/)
  *
- * If you are creating a modal dialog, you probably want to use the [Dialog](/api/dialog/) component
+ * If you are creating a modal dialog, you probably want to use the [Dialog](https://material-ui.com/api/dialog/) component
  * rather than directly using Modal.
  *
  * This component shares many concepts with [react-overlays](https://react-bootstrap.github.io/react-overlays/#modals).

diff --git a/packages/material-ui/src/NoSsr/NoSsr.d.ts b/packages/material-ui/src/NoSsr/NoSsr.d.ts
@@ -10,10 +10,11 @@ export interface NoSsrProps {
  * NoSsr purposely removes components from the subject of Server Side Rendering (SSR).
  *
  * This component can be useful in a variety of situations:
- * - Escape hatch for broken dependencies not supporting SSR.
- * - Improve the time-to-first paint on the client by only rendering above the fold.
- * - Reduce the rendering time on the server.
- * - Under too heavy server load, you can turn on service degradation.
+ *
+ * -   Escape hatch for broken dependencies not supporting SSR.
+ * -   Improve the time-to-first paint on the client by only rendering above the fold.
+ * -   Reduce the rendering time on the server.
+ * -   Under too heavy server load, you can turn on service degradation.
  *
  * Demos:
  * - [No Ssr](https://material-ui.com/components/no-ssr/)

diff --git a/packages/material-ui/src/RootRef/RootRef.d.ts b/packages/material-ui/src/RootRef/RootRef.d.ts
@@ -7,16 +7,17 @@ export interface RootRefProps<T = any> {
 /**
  * ⚠️⚠️⚠️
  * If you want the DOM element of a Material-UI component check out
- * [FAQ: How can I access the DOM element?](/getting-started/faq/#how-can-i-access-the-dom-element)
+ * [FAQ: How can I access the DOM element?](https://material-ui.com/getting-started/faq/#how-can-i-access-the-dom-element)
  * first.
  *
  * This component uses `findDOMNode` which is deprecated in React.StrictMode.
  *
  * Helper component to allow attaching a ref to a
  * wrapped element to access the underlying DOM element.
  *
- * It's highly inspired by https://github.com/facebook/react/issues/11401#issuecomment-340543801.
+ * It's highly inspired by <https://github.com/facebook/react/issues/11401#issuecomment-340543801>.
  * For example:
+ *
  * ```jsx
  * import React from 'react';
  * import RootRef from '@material-ui/core/RootRef';

diff --git a/packages/material-ui/src/Slide/Slide.d.ts b/packages/material-ui/src/Slide/Slide.d.ts
@@ -9,7 +9,7 @@ export interface SlideProps extends TransitionProps {
 }
 
 /**
- * The Slide transition is used by the [Drawer](/components/drawers/) component.
+ * The Slide transition is used by the [Drawer](https://material-ui.com/components/drawers/) component.
  * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.
  *
  * Demos:

diff --git a/packages/material-ui/src/TextField/TextField.d.ts b/packages/material-ui/src/TextField/TextField.d.ts
@@ -83,12 +83,12 @@ export type TextFieldClassKey = 'root';
  * It's important to understand that the text field is a simple abstraction
  * on top of the following components:
  *
- * - [FormControl](/api/form-control/)
- * - [InputLabel](/api/input-label/)
- * - [FilledInput](/api/filled-input/)
- * - [OutlinedInput](/api/outlined-input/)
- * - [Input](/api/input/)
- * - [FormHelperText](/api/form-helper-text/)
+ * -   [FormControl](https://material-ui.com/api/form-control/)
+ * -   [InputLabel](https://material-ui.com/api/input-label/)
+ * -   [FilledInput](https://material-ui.com/api/filled-input/)
+ * -   [OutlinedInput](https://material-ui.com/api/outlined-input/)
+ * -   [Input](https://material-ui.com/api/input/)
+ * -   [FormHelperText](https://material-ui.com/api/form-helper-text/)
  *
  * If you wish to alter the props applied to the `input` element, you can do so as follows:
  *
@@ -103,8 +103,8 @@ export type TextFieldClassKey = 'root';
  * For advanced cases, please look at the source of TextField by clicking on the
  * "Edit this page" button above. Consider either:
  *
- * - using the upper case props for passing values directly to the components
- * - using the underlying components directly as shown in the demos
+ * -   using the upper case props for passing values directly to the components
+ * -   using the underlying components directly as shown in the demos
  *
  * Demos:
  * - [Autocomplete](https://material-ui.com/components/autocomplete/)

diff --git a/packages/material-ui/src/Zoom/Zoom.d.ts b/packages/material-ui/src/Zoom/Zoom.d.ts
@@ -9,7 +9,7 @@ export interface ZoomProps extends TransitionProps {
 
 /**
  * The Zoom transition can be used for the floating variant of the
- * [Button](/components/buttons/#floating-action-buttons) component.
+ * [Button](https://material-ui.com/components/buttons/#floating-action-buttons) component.
  * It uses [react-transition-group](https://github.com/reactjs/react-transition-group) internally.
  *
  * Demos: