docs: generate website documents correctly for 2.0 (#1494)

Co-authored-by: Christian Murphy <[email protected]>

.eslintignore

@@ -12,6 +12,7 @@ examples/**/node_modules/**/*.*
 
 packages/**/fixtures/**/*.mdx
 packages/**/test/**/*.mdx
+packages/**/*.d.ts
 packages/gatsby-theme-mdx/src/components/header.js
 packages/gatsby-theme-mdx/src/components/layout.js
 packages/gatsby-theme-mdx/src/components/search.js

.eslintrc.yml

@@ -33,6 +33,10 @@ rules:
   import/no-extraneous-dependencies: error
   prettier/prettier: error
   no-console: off
+  import/no-unresolved:
+    - error
+    - ignore:
+        - '@mdx-js/react'
   react/prop-types: off
   react/display-name: off
   react/no-children-prop: off
@@ -43,13 +47,13 @@ settings:
     version: 16.3.2
 
 overrides:
-  - files: '*.mdx'
+  - files: '*.{md,mdx}'
     extends:
       - plugin:mdx/recommended
       - plugin:mdx/overrides
     rules:
       import/no-extraneous-dependencies: 0
-      prettier/prettier: 0
+      prettier/prettier: error
 
   - files:
       - '**/test/**/*.js'

.remarkrc.js

@@ -1,6 +1,6 @@
 module.exports = {
   plugins: [
-    './packages/remark-mdx',
+    'remark-frontmatter',
     'preset-wooorm',
     'preset-prettier',
     ['retext', false],

docs/advanced/api.mdx

@@ -130,13 +130,15 @@ const visit = require('unist-util-visit')
 const remove = require('unist-util-remove')
 const yaml = require('yaml')
 
-const file = vfile(`
+const file = vfile(
+  `
 ---
 title: Hello, MDX
 ---
 
-I <3 Markdown and JSX
-`)
+I &lt;3 Markdown and JSX {/* < must be escaped for \`@mdx-js/mdx@2\` */}
+`.trimStart() // there should be no space before frontmatter for `remark-frontmatter@3`, this can be guaranteed with `trimStart`
+)
 
 function extractFrontmatter() {
   return function transformer(tree, file) {

docs/getting-started/create-react-app.mdx

@@ -95,8 +95,5 @@ Finally, see [Support][] if you’re still running into problems.
 [cra]: https://github.com/facebook/create-react-app
 [loader]: https://github.com/mdx-js/mdx/tree/main/packages/loader
 [babel-loader]: https://webpack.js.org/loaders/babel-loader/
-
-<!-- To do: update to point to website if that’s working -->
-
-[typescript]: https://github.com/mdx-js/mdx/blob/main/docs/advanced/typescript.mdx
+[typescript]: https://mdxjs.com/advanced/typescript
 [support]: https://mdxjs.com/support

docs/getting-started/table-of-components.mdx

@@ -1,27 +1,27 @@
-| Tag             | Name                                                                 | Syntax                                              |
-| --------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
-| `p`             | [Paragraph](https://github.com/syntax-tree/mdast#paragraph)          |                                                     |
-| `h1`            | [Heading 1](https://github.com/syntax-tree/mdast#heading)            | `#`                                                 |
-| `h2`            | [Heading 2](https://github.com/syntax-tree/mdast#heading)            | `##`                                                |
-| `h3`            | [Heading 3](https://github.com/syntax-tree/mdast#heading)            | `###`                                               |
-| `h4`            | [Heading 4](https://github.com/syntax-tree/mdast#heading)            | `####`                                              |
-| `h5`            | [Heading 5](https://github.com/syntax-tree/mdast#heading)            | `#####`                                             |
-| `h6`            | [Heading 6](https://github.com/syntax-tree/mdast#heading)            | `######`                                            |
-| `blockquote`    | [Blockquote](https://github.com/syntax-tree/mdast#blockquote)        | `>`                                                 |
-| `ul`            | [List](https://github.com/syntax-tree/mdast#list)                    | `-`                                                 |
-| `ol`            | [Ordered list](https://github.com/syntax-tree/mdast#list)            | `1.`                                                |
-| `li`            | [List item](https://github.com/syntax-tree/mdast#listitem)           |                                                     |
-| `table`         | [Table](https://github.com/syntax-tree/mdast#table)                  |                                                     |
-| `thead`         | [Table head](https://github.com/syntax-tree/mdast#table)             |                                                     |
-| `tbody`         | [Table body](https://github.com/syntax-tree/mdast#table)             |                                                     |
-| `tr`            | [Table row](https://github.com/syntax-tree/mdast#tablerow)           |                                                     |
-| `td`/`th`       | [Table cell](https://github.com/syntax-tree/mdast#tablecell)         |                                                     |
-| `code`          | [Code](https://github.com/syntax-tree/mdast#code)                    | ` ```code``` `                                      |
-| `inlineCode`    | [InlineCode](https://github.com/syntax-tree/mdast#inlinecode)        | `` `inlineCode` ``                                  |
-| `pre`           | [Code](https://github.com/syntax-tree/mdast#code)                    | ` ```code``` `                                      |
-| `em`            | [Emphasis](https://github.com/syntax-tree/mdast#emphasis)            | `_emphasis_`                                        |
-| `strong`        | [Strong](https://github.com/syntax-tree/mdast#strong)                | `**strong**`                                        |
-| `del`           | [Delete](https://github.com/syntax-tree/mdast#delete)                | `~~strikethrough~~`                                 |
-| `hr`            | [Thematic break](https://github.com/syntax-tree/mdast#thematicbreak) | `---` or `***`                                      |
-| `a`             | [Link](https://github.com/syntax-tree/mdast#link)                    | `<https://mdxjs.com>` or `[MDX](https://mdxjs.com)` |
-| `img`           | [Image](https://github.com/syntax-tree/mdast#image)                  | `![alt](https://mdx-logo.now.sh)`                   |
+| Tag          | Name                                                                 | Syntax                                              |
+| ------------ | -------------------------------------------------------------------- | --------------------------------------------------- |
+| `p`          | [Paragraph](https://github.com/syntax-tree/mdast#paragraph)          |                                                     |
+| `h1`         | [Heading 1](https://github.com/syntax-tree/mdast#heading)            | `#`                                                 |
+| `h2`         | [Heading 2](https://github.com/syntax-tree/mdast#heading)            | `##`                                                |
+| `h3`         | [Heading 3](https://github.com/syntax-tree/mdast#heading)            | `###`                                               |
+| `h4`         | [Heading 4](https://github.com/syntax-tree/mdast#heading)            | `####`                                              |
+| `h5`         | [Heading 5](https://github.com/syntax-tree/mdast#heading)            | `#####`                                             |
+| `h6`         | [Heading 6](https://github.com/syntax-tree/mdast#heading)            | `######`                                            |
+| `blockquote` | [Blockquote](https://github.com/syntax-tree/mdast#blockquote)        | `>`                                                 |
+| `ul`         | [List](https://github.com/syntax-tree/mdast#list)                    | `-`                                                 |
+| `ol`         | [Ordered list](https://github.com/syntax-tree/mdast#list)            | `1.`                                                |
+| `li`         | [List item](https://github.com/syntax-tree/mdast#listitem)           |                                                     |
+| `table`      | [Table](https://github.com/syntax-tree/mdast#table)                  |                                                     |
+| `thead`      | [Table head](https://github.com/syntax-tree/mdast#table)             |                                                     |
+| `tbody`      | [Table body](https://github.com/syntax-tree/mdast#table)             |                                                     |
+| `tr`         | [Table row](https://github.com/syntax-tree/mdast#tablerow)           |                                                     |
+| `td`/`th`    | [Table cell](https://github.com/syntax-tree/mdast#tablecell)         |                                                     |
+| `code`       | [Code](https://github.com/syntax-tree/mdast#code)                    | ` ```code``` `                                      |
+| `inlineCode` | [InlineCode](https://github.com/syntax-tree/mdast#inlinecode)        | `` `inlineCode` ``                                  |
+| `pre`        | [Code](https://github.com/syntax-tree/mdast#code)                    | ` ```code``` `                                      |
+| `em`         | [Emphasis](https://github.com/syntax-tree/mdast#emphasis)            | `_emphasis_`                                        |
+| `strong`     | [Strong](https://github.com/syntax-tree/mdast#strong)                | `**strong**`                                        |
+| `del`        | [Delete](https://github.com/syntax-tree/mdast#delete)                | `~~strikethrough~~`                                 |
+| `hr`         | [Thematic break](https://github.com/syntax-tree/mdast#thematicbreak) | `---` or `***`                                      |
+| `a`          | [Link](https://github.com/syntax-tree/mdast#link)                    | `<https://mdxjs.com>` or `[MDX](https://mdxjs.com)` |
+| `img`        | [Image](https://github.com/syntax-tree/mdast#image)                  | `![alt](https://mdx-logo.now.sh)`                   |

docs/guides/mdx-embed.md

@@ -22,7 +22,8 @@ export default props => <MDXEmbedProvider>{props.children}</MDXEmbedProvider>
 ### Usage
 
 ```mdx
-// some-mdx-file.mdx
+<!-- some-mdx-file.mdx -->
+
 #### My cool pen
 
 Here's a pen, and some other blog post text

examples/react-static/package.json

@@ -23,7 +23,6 @@
     "react-static-plugin-source-filesystem": "^7.4.2"
   },
   "devDependencies": {
-    "eslint-config-react-tools": "^1.1.7",
     "serve": "^11.3.2"
   }
 }

package.json

@@ -19,9 +19,9 @@
     "docs-build": "gatsby build",
     "docs-deploy": "vercel && vercel alias $(pbpaste) mdxjs.com && vercel alias $(pbpaste) www.mdxjs.com",
     "format": "yarn lint --fix",
-    "lint": "eslint . --cache --ext js,jsx -f friendly",
+    "lint": "eslint . --cache --ext md,mdx,js,jsx -f friendly",
     "vercel-build": "yarn build && yarn docs-build",
-    "postinstall": "yarn-deduplicate || exit 0",
+    "postinstall": "yarn-deduplicate --strategy fewer && patch-package || exit 0",
     "prepublishOnly": "yarn build",
     "publish": "lerna publish --force-publish=\"*\"",
     "publish-ci": "lerna publish -y --canary --preid ci --pre-dist-tag ci",
@@ -45,7 +45,7 @@
     "eslint-config-xo": "^0.33.0",
     "eslint-formatter-friendly": "^7.0.0",
     "eslint-plugin-import": "^2.22.0",
-    "eslint-plugin-mdx": "^1.8.0",
+    "eslint-plugin-mdx": "^1.11.1",
     "eslint-plugin-prettier": "^3.1.4",
     "eslint-plugin-react": "^7.21.0",
     "gatsby": "^2.24.3",
@@ -54,20 +54,24 @@
     "jest": "^26.6.0",
     "lerna": "^3.22.1",
     "lint-staged": "^10.5.0",
+    "patch-package": "^6.4.7",
+    "postinstall-postinstall": "^2.1.0",
     "prettier": "^2.1.0",
+    "remark-frontmatter": "^2.0.0",
     "remark-preset-prettier": "^0.4.0",
     "remark-preset-wooorm": "^8.0.0",
     "rimraf": "^3.0.0",
     "typescript": "^4.0.0",
     "yarn-deduplicate": "^3.0.0"
   },
   "resolutions": {
+    "eslint": "^7.22.0",
     "gatsby-plugin-mdx/@mdx-js/mdx": "^1.0.0",
     "gatsby-plugin-mdx/@mdx-js/react": "^1.0.0"
   },
   "husky": {
     "hooks": {
-      "#pre-commit": "lint-staged"
+      "pre-commit": "lint-staged"
     }
   },
   "jest": {

packages/gatsby-theme-mdx/package.json

@@ -17,7 +17,8 @@
   },
   "peerDependencies": {
     "react": ">=16",
-    "react-dom": ">=16"
+    "react-dom": ">=16",
+    "gatsby": "^2.0.0"
   },
   "dependencies": {
     "@blocks/kit": "0.0.28",
@@ -31,7 +32,6 @@
     "@rebass/emotion": "3.2.0",
     "@theme-ui/components": "^0.3.1",
     "@theme-ui/preset-system": "0.3.0",
-    "gatsby": "2.24.3",
     "gatsby-plugin-catch-links": "2.3.11",
     "gatsby-plugin-compile-es6-packages": "2.1.0",
     "gatsby-plugin-emotion": "4.3.10",

packages/gatsby-theme-mdx/src/components/layout.js

@@ -117,7 +117,7 @@ const Sidebar = ({open, ...props}) => (
         position: 'relative',
         maxHeight: '100vh',
         overflowY: 'auto',
-        WebkitOverflowScrolling: 'touch',
+        webkitOverflowScrolling: 'touch',
         bg: 'background',
         transition: 'background-color .4s ease-out',
         pb: 4,

packages/gatsby-theme-mdx/src/components/skip-nav.js

@@ -1,5 +1,8 @@
+import '@reach/skip-nav/styles.css'
+
 import React from 'react'
 import {SkipNavLink as Link} from '@reach/skip-nav'
+
 export {SkipNavContent} from '@reach/skip-nav'
 
 export const SkipNavLink = props => (

packages/gatsby-theme-mdx/src/pages/.eslintrc

@@ -0,0 +1,11 @@
+{
+  "overrides": [
+    {
+      "files": "./conf.mdx",
+      "globals": {
+        "Speaker": "readonly",
+        "SpeakerList": "readonly"
+      }
+    }
+  ]
+}

packages/gatsby-theme-mdx/src/pages/conf.mdx

@@ -148,5 +148,4 @@ Reach out to us on [Twitter][].
 
 [first commit]: https://github.com/mdx-js/mdx/commit/dee47dc20b08d534132e3b966cdccf3b88c7bca5
 [twitter]: https://twitter.com/mdx_js
-[conf]: https://mdxjs.com/conf
 [coc]: https://github.com/partycorgi/partycorgi/blob/corgi/CODE_OF_CONDUCT.md

patches/gatsby-theme-mdx1+1.6.22.patch

@@ -0,0 +1,22 @@
+diff --git a/node_modules/gatsby-theme-mdx1/src/components/header.js b/node_modules/gatsby-theme-mdx1/src/components/header.js
+index e82254e..1978a3b 100644
+--- a/node_modules/gatsby-theme-mdx1/src/components/header.js
++++ b/node_modules/gatsby-theme-mdx1/src/components/header.js
+@@ -1,7 +1,7 @@
+ import React from 'react'
+ import {Link} from 'gatsby'
+ import {css} from 'theme-ui'
+-import pkg from '@mdx-js/mdx/package.json'
++import pkg from '../../../../packages/mdx/package.json'
+ import Burger from './burger'
+ import theme from './theme'
+ import DarkToggle from './dark-toggle'
+diff --git a/node_modules/gatsby-theme-mdx1/src/components/skip-nav.js b/node_modules/gatsby-theme-mdx1/src/components/skip-nav.js
+index ad2d200..66baefb 100644
+--- a/node_modules/gatsby-theme-mdx1/src/components/skip-nav.js
++++ b/node_modules/gatsby-theme-mdx1/src/components/skip-nav.js
+@@ -1,3 +1,4 @@
++import '@reach/skip-nav/styles.css'
+ import React from 'react'
+ import {SkipNavLink as Link} from '@reach/skip-nav'
+ export {SkipNavContent} from '@reach/skip-nav'