[docs] convert app to ESM, update MDX to v2 (expo#18947)

Co-authored-by: Jon Samp <[email protected]>

Author: Simek

docs/.eslintrc.cjs

@@ -11,5 +11,7 @@ module.exports = {
     'lodash/import-scope': [2, 'method'],
     '@next/next/no-img-element': 0,
     'react/jsx-curly-brace-presence': [1, { propElementValues: 'ignore' }],
+    // https://github.com/emotion-js/emotion/issues/2878
+    'react/no-unknown-property': ['error', { 'ignore': ['css'] }]
   },
 };

docs/.gitignore

@@ -5,3 +5,6 @@ out/
 
 # copied in next.config.js
 pages/versions/latest/
+
+# staticly generated constants
+public/static/constants

docs/README.md

@@ -1,11 +1,13 @@
 # Expo Documentation
 
-This is the public documentation for **Expo**, its SDK, client, and services.
+This is the public documentation for **Expo**, its SDK, client, and services, like **EAS**.
 
-You can access this documentation online at https://docs.expo.dev/. It's built using Next.js on top of the https://github.com/vercel/docs codebase.
+This documentation is built using Next.js and you can access it online at https://docs.expo.dev/.
 
+> **Note**
 > **Contributors:** Please make sure that you edit the docs in the `pages/versions/unversioned` directory if you want your changes to apply to the next SDK version too!
 
+> **Note**
 > If you are looking for Expo Documentation Writing Style guidelines, please refer [Expo Documentation Style Guide](https://github.com/expo/expo/blob/main/guides/Expo%20Documentation%20Writing%20Style%20Guide.md).
 
 ## Running Locally
@@ -41,7 +43,8 @@ yarn run export-server
 
 You can find the content source of the documentation inside the `pages/` directory. Documentation is mostly written in markdown with the help of some React components (for Snack embeds, etc). Our API documentation can all be found under `pages/versions/`; we keep separate versions of the documentation for each SDK version currently supported in Expo Go, see ["A note about versioning"](#a-note-about-versioning) for more info. The routes and navbar are automatically inferred from the directory structure within `versions`.
 
-> Note: We are currently in the process of moving our API documentation to being auto-generated using `expotools`'s `GenerateDocsAPIData` command.
+> **Note**
+> We are currently in the process of moving our API documentation to being auto-generated using `expotools`'s `GenerateDocsAPIData` command.
 
 Each markdown page can be provided metadata in the heading, distinguished by:
 
@@ -151,13 +154,14 @@ You can validate all current links by running `yarn lint-links`.
 
 ### Updating latest version of docs
 
-When we release a new SDK, we copy the `unversioned` directory, and rename it to the new version. Latest version of docs is read from **package.json** so make sure to update the `version` key there as well. However, if you update the `version` key there, you need to `rm -rf node_modules/.cache/` before the change is picked up (why? [read this](https://github.com/vercel/next.js/blob/4.0.0/examples/with-universal-configuration/README.md#caveats)).
+When we release a new SDK, we copy the `unversioned` directory, and rename it to the new version. Latest version of docs is read from **package.json** so make sure to update the `version` key there as well. 
 
 Make sure to also grab the upgrade instructions from the release notes blog post and put them in `upgrading-expo-sdk-walkthrough.md`.
 
 That's all you need to do. The `versions` directory is listed on server start to find all available versions. The routes and navbar contents are automatically inferred from the directory structure within `versions`.
 
-Because the navbar is automatically generated from the directory structure, the default ordering of the links under each section is alphabetical. However, for many sections, this is not ideal UX. So, if you wish to override the alphabetical ordering, manipulate page titles in **navigation.js**.
+Because the navbar is automatically generated from the directory structure, the default ordering of the links under each section is alphabetical. However, for many sections, this is not ideal UX. 
+So, if you wish to override the alphabetical ordering, manipulate page titles in **constants/navigation.js**.
 
 ### Syncing app.json / app.config.js with the schema
 
@@ -226,7 +230,8 @@ import SnackInline from '~/components/plugins/SnackInline';
 
 ### Embedding multiple options of code
 
-Sometimes it's useful to show multiple ways of doing something, for instance maybe you'd like to have an example using a React class component, and also an example of a functional component. The `Tabs` plugin is really useful for this, and this is how you'd use it an a markdown file:
+Sometimes it's useful to show multiple ways of doing something, for instance maybe you'd like to have an example using a React class component, and also an example of a functional component. 
+The `Tabs` plugin is really useful for this, and this is how you'd use it in a markdown file:
 
 <!-- prettier-ignore -->
 ```jsx
@@ -241,11 +246,9 @@ import { Tab, Tabs } from '~/components/plugins/Tabs';
     /* @end */
     };
 
-
 </Tab>
 <Tab label="Add 1 Another Way">
 
-
     addOne = async x => {
     /* @info This text will be shown onHover */
     return x++;
@@ -258,15 +261,16 @@ import { Tab, Tabs } from '~/components/plugins/Tabs';
 
 n.b. The components should not be indented or they will not be parsed correctly.
 
-### Excluding pages from Docsearch
+### Excluding pages from DocSearch
 
 To ignore a page from the search result, use `hideFromSearch: true` on that page. This removes the `<meta name="docsearch:version">` tag from that page and filters it from our facet-based search.
 
-Please note that `hideFromSearch` only prevents the page from showing up in the internal docs search (Algolia). The page will still show up in search engine results like Google. For a page to be hidden even from search engine results, you need to edit the sitemap that is generated via our Next.js config (**config.js**).
+Please note that `hideFromSearch` only prevents the page from showing up in the internal docs search (Algolia). The page will still show up in search engine results like Google. 
+For a page to be hidden even from search engine results, you need to edit the sitemap that is generated via our Next.js config (**next.config.js**).
 
 ### Excluding directories from the sidebar
 
-Certain directories are excluded from the sidebar in order to prevent it from getting too long and unnavigable. You can find a list of these directories, and add new ones, in **navigation.js** under `hiddenSections`.
+Certain directories are excluded from the sidebar in order to prevent it from getting too long and unnavigable. You can find a list of these directories, and add new ones, in **constants/navigation.js** under `hiddenSections`.
 
 If you just want to hide a single page from the sidebar, set `hideInSidebar: true` in the page metadata.
 
@@ -296,10 +300,9 @@ import { Terminal } from '~/ui/components/Snippet';
 
 Please commit any sizeable diffs that are the result of `prettier` separately to make reviews as easy as possible.
 
-If you have a codeblock using `/* @info */` highlighting, use `<!-- prettier-ignore -->` on the block and take care to preview the block in the browser to ensure that the indentation is correct - the highlighting annotation will sometimes swallow newlines.
+If you have a code block using `/* @info */` highlighting, use `{/* prettier-ignore */}` on the block and take care to preview the block in the browser to ensure that the indentation is correct - the highlighting annotation will sometimes swallow newlines.
 
 ## TODOs:
 
 - Handle image sizing in imports better
-- Read from the appropriate version (configurable) of the React Native docs, not just main
 - Make Snack embeds work; these are marked in some of the React Native docs but they are just imported as plain JS code blocks

docs/common/create-permalinked-component.tsx

@@ -0,0 +1,43 @@
+import * as React from 'react';
+
+import { AdditionalProps, HeadingType } from '~/common/headingManager';
+import Permalink from '~/components/Permalink';
+
+type Options = {
+  customIconStyle?: React.CSSProperties;
+  baseNestingLevel?: number;
+  sidebarType?: HeadingType;
+};
+
+type PermalinkedComponentProps = React.PropsWithChildren<{ level?: number } & AdditionalProps>;
+
+const isDev = process.env.NODE_ENV === 'development';
+
+export const createPermalinkedComponent = (
+  BaseComponent: React.ComponentType<React.PropsWithChildren<object>>,
+  options?: Options
+) => {
+  const { customIconStyle, baseNestingLevel, sidebarType = HeadingType.Text } = options || {};
+  return ({ children, level, ...props }: PermalinkedComponentProps) => {
+    const cleanChildren = React.Children.map(children, child => {
+      if (React.isValidElement(child) && child?.props?.href) {
+        isDev &&
+          console.warn(
+            `It looks like the header on this page includes a link, this is an invalid pattern, nested link will be removed!`,
+            child?.props?.href
+          );
+        return child?.props?.children;
+      }
+      return child;
+    });
+    const nestingLevel = baseNestingLevel != null ? (level ?? 0) + baseNestingLevel : undefined;
+    return (
+      <Permalink
+        nestingLevel={nestingLevel}
+        customIconStyle={customIconStyle}
+        additionalProps={{ ...props, sidebarType }}>
+        <BaseComponent>{cleanChildren}</BaseComponent>
+      </Permalink>
+    );
+  };
+};

docs/common/error-utilities.ts

@@ -1,4 +1,4 @@
-import { VERSIONS } from '~/constants/versions.cjs';
+import versions from '~/public/static/constants/versions.json';
 
 export function getRedirectPath(redirectPath: string): string {
   // index.html is no longer a thing in our docs
@@ -73,7 +73,7 @@ function getVersionFromPath(path: string) {
 }
 
 // Filter unversioned and latest out, so we end up with v34, etc.
-const supportedVersions = VERSIONS.filter(v => v.match(/^v/));
+const supportedVersions = versions.VERSIONS.filter(v => v.match(/^v/));
 
 // Return true if the version is still included in documentation
 function isVersionDocumented(path: string) {

docs/common/test-utilities.tsx

@@ -0,0 +1,17 @@
+import { render, RenderOptions } from '@testing-library/react';
+import GithubSlugger from 'github-slugger';
+import { PropsWithChildren, ReactElement } from 'react';
+
+import { HeadingManager } from '~/common/headingManager';
+import { HeadingsContext } from '~/components/page-higher-order/withHeadingManager';
+
+const Wrapper = ({ children }: PropsWithChildren<object>) => (
+  <HeadingsContext.Provider value={new HeadingManager(new GithubSlugger(), { headings: [] })}>
+    {children}
+  </HeadingsContext.Provider>
+);
+
+export const renderWithHeadings = (
+  element: ReactElement,
+  options?: Omit<RenderOptions, 'wrapper'>
+) => render(element, { wrapper: Wrapper, ...options });

docs/common/translate-markdown.tsx

@@ -1,42 +1,13 @@
-import * as React from 'react';
+import { createPermalinkedComponent } from './create-permalinked-component';
 
-import { AdditionalProps } from './headingManager';
-
-import Permalink from '~/components/Permalink';
 import { Code, InlineCode } from '~/components/base/code';
 import { H1, H2, H3, H4 } from '~/components/base/headings';
 import Link from '~/components/base/link';
 import { UL, OL, LI } from '~/components/base/list';
 import { PDIV, B, Quote } from '~/components/base/paragraph';
-import { BareWorkflowCollapsible, ExpoKitCollapsible } from '~/ui/components/Collapsible';
 import { Cell, HeaderCell, Row, Table, TableHead } from '~/ui/components/Table';
 import { KBD } from '~/ui/components/Text';
 
-type Options = {
-  customIconStyle?: React.CSSProperties;
-  baseNestingLevel?: number;
-};
-
-type PermalinkedComponentProps = React.PropsWithChildren<{ level?: number } & AdditionalProps>;
-
-const createPermalinkedComponent = (
-  BaseComponent: React.ComponentType<React.PropsWithChildren<object>>,
-  options?: Options
-) => {
-  const { customIconStyle, baseNestingLevel } = options || {};
-  return ({ children, level, ...props }: PermalinkedComponentProps) => {
-    const nestingLevel = baseNestingLevel != null ? (level ?? 0) + baseNestingLevel : undefined;
-    return (
-      <Permalink
-        nestingLevel={nestingLevel}
-        customIconStyle={customIconStyle}
-        additionalProps={props}>
-        <BaseComponent>{children}</BaseComponent>
-      </Permalink>
-    );
-  };
-};
-
 // When using inline markdown, we need to remove the document layout wrapper.
 // Always set this to `null` to overwrite the global MDX provider.
 export const wrapper = null;
@@ -50,8 +21,8 @@ export const h1 = createPermalinkedComponent(H1, { baseNestingLevel: 1 });
 export const h2 = createPermalinkedComponent(H2, { baseNestingLevel: 2 });
 export const h3 = createPermalinkedComponent(H3, { baseNestingLevel: 3 });
 export const h4 = createPermalinkedComponent(H4, { baseNestingLevel: 4 });
-export const code = Code;
-export const inlineCode = InlineCode;
+export const code = InlineCode;
+export const pre = Code;
 export const a = Link;
 export const blockquote = Quote;
 export const table = Table;
@@ -60,11 +31,3 @@ export const tr = Row;
 export const th = HeaderCell;
 export const td = Cell;
 export const kbd = KBD;
-export const expokitDetails = ExpoKitCollapsible;
-export const bareworkflowDetails = BareWorkflowCollapsible;
-export const propertyAnchor = createPermalinkedComponent(PDIV, {
-  baseNestingLevel: 3,
-});
-export const subpropertyAnchor = createPermalinkedComponent(PDIV, {
-  baseNestingLevel: 3,
-});

docs/components/DocumentationPage.tsx

@@ -1,5 +1,5 @@
 import { css } from '@emotion/react';
-import { theme } from '@expo/styleguide';
+import { breakpoints, theme } from '@expo/styleguide';
 import some from 'lodash/some';
 import Router, { NextRouter } from 'next/router';
 import * as React from 'react';
@@ -13,9 +13,8 @@ import DocumentationSidebarRight, {
 } from '~/components/DocumentationSidebarRight';
 import Head from '~/components/Head';
 import { H1 } from '~/components/base/headings';
-import navigation from '~/constants/navigation.cjs';
-import * as Constants from '~/constants/theme';
-import { usePageApiVersion } from '~/providers/page-api-version';
+import { PageApiVersionContextType, usePageApiVersion } from '~/providers/page-api-version';
+import navigation from '~/public/static/constants/navigation.json';
 import { NavigationRoute } from '~/types/common';
 import { Header } from '~/ui/components/Header';
 import { Sidebar } from '~/ui/components/Sidebar';
@@ -31,7 +30,7 @@ const STYLES_DOCUMENT = css`
     background-color: ${theme.border.default};
   }
 
-  @media screen and (max-width: ${Constants.breakpoints.mobile}) {
+  @media screen and (max-width: ${breakpoints.medium + 124}px) {
     padding: 20px 16px 48px 16px;
   }
 `;
@@ -43,7 +42,7 @@ type Props = React.PropsWithChildren<{
   tocVisible: boolean;
   /** If the page should not show up in the Algolia Docsearch results */
   hideFromSearch?: boolean;
-  version: string;
+  version: PageApiVersionContextType['version'];
 }>;
 
 type State = {
@@ -76,7 +75,7 @@ class DocumentationPageWithApiVersion extends React.Component<Props, State> {
   }
 
   private handleResize = () => {
-    if (WindowUtils.getViewportSize().width >= Constants.breakpoints.mobileValue) {
+    if (WindowUtils.getViewportSize().width >= breakpoints.medium + 124) {
       this.setState({ isMobileMenuVisible: false });
       window.scrollTo(0, 0);
     }
@@ -135,9 +134,9 @@ class DocumentationPageWithApiVersion extends React.Component<Props, State> {
 
   private getRoutes = (): NavigationRoute[] => {
     if (this.isReferencePath()) {
-      return (navigation as any).reference[this.props.version];
+      return navigation.reference[this.props.version] as NavigationRoute[];
     } else {
-      return (navigation as any)[this.getActiveTopLevelSection()];
+      return navigation[this.getActiveTopLevelSection()] as NavigationRoute[];
     }
   };
 

docs/components/DocumentationSidebarRight.tsx

@@ -1,19 +1,19 @@
 import { css } from '@emotion/react';
+import { breakpoints } from '@expo/styleguide';
 import * as React from 'react';
 
-import { BASE_HEADING_LEVEL, Heading, HeadingManager } from '../common/headingManager';
 import DocumentationSidebarRightLink from './DocumentationSidebarRightLink';
 
+import { BASE_HEADING_LEVEL, Heading, HeadingManager } from '~/common/headingManager';
 import withHeadingManager, {
   HeadingManagerProps,
 } from '~/components/page-higher-order/withHeadingManager';
-import * as Constants from '~/constants/theme';
 
 const STYLES_SIDEBAR = css`
   padding: 20px 24px 24px 24px;
   width: 280px;
 
-  @media screen and (max-width: ${Constants.breakpoints.mobile}) {
+  @media screen and (max-width: ${breakpoints.medium + 124}px) {
     width: 100%;
   }
 `;