Use custom ID format that works better with MDX 2 (#4105)

* Fix two unicode whitespaces which are invalid

* Use custom ID format that works better with MDX 2

* Fix sebastian

* remark-slug as dev dep

Author: wooorm

beta/package.json

@@ -76,6 +76,7 @@
     "remark-external-links": "^7.0.0",
     "remark-html": "^12.0.0",
     "remark-images": "^2.0.0",
+    "remark-slug": "^7.0.0",
     "remark-unwrap-images": "^2.0.0",
     "retext": "^7.0.1",
     "retext-smartypants": "^4.0.0",
@@ -93,4 +94,4 @@
     "budgetPercentIncreaseRed": 10,
     "showDetails": true
   }
-}
+}

beta/plugins/remark-header-custom-ids.js

@@ -30,16 +30,34 @@ module.exports = ({
   slugs.reset();
   return function transformer(tree) {
     visit(tree, 'heading', (node) => {
-      // Support custom-id syntax.
-      const rawHeader = toString(node);
-      const match = /^.+(\s*\{#([\p{L}0-9\-_]+?)\}\s*)$/u.exec(rawHeader);
-      const id = match ? match[2] : slugs.slug(rawHeader, maintainCase);
-      if (match) {
-        // Remove the custom ID part from the text node.
-        const lastNode = node.children[node.children.length - 1];
-        lastNode.value = lastNode.value.replace(match[1], '');
+      const children = node.children;
+      let tail = children[children.length - 1];
+
+      // A bit weird: this is to support MDX 2 comments in expressions,
+      // while we’re still on MDX 1, which doesn’t support them.
+      if (!tail || tail.type !== 'text' || tail.value !== '/}') {
+        return
       }
 
+      tail = children[children.length - 2]
+
+      if (!tail && tail.type !== 'emphasis') {
+        return
+      }
+
+      const id = toString(tail)
+
+      tail = children[children.length - 3]
+
+      if (!tail || tail.type !== 'text' || !tail.value.endsWith('{/')) {
+        return
+      }
+
+      // Remove the emphasis and trailing `/}`
+      children.splice(children.length - 2, 2)
+      // Remove the `{/`
+      tail.value = tail.value.replace(/[ \t]*\{\/$/, '')
+
       const data = patch(node, 'data', {});
 
       patch(data, 'id', id);

beta/scripts/generateHeadingIDs.js

@@ -2,9 +2,16 @@
  * Copyright (c) Facebook, Inc. and its affiliates.
  */
 
+// To do: Make this ESM.
+// To do: properly check heading numbers (headings with the same text get
+// numbered, this script doesn’t check that).
+
+const assert = require('assert');
 const fs = require('fs');
 const GithubSlugger = require('github-slugger');
 
+let modules
+
 function walk(dir) {
   let results = [];
   const list = fs.readdirSync(dir);
@@ -31,15 +38,25 @@ function addHeaderID(line, slugger) {
   if (!line.startsWith('#')) {
     return line;
   }
-  // check if it already has an id
-  if (/\{#[^}]+\}/.test(line)) {
-    return line;
+
+  const match = /^(#+\s+)(.+?)(\s*\{(?:\/\*|#)([^\}\*\/]+)(?:\*\/)?\}\s*)?$/.exec(line);
+  const before = match[1] + match[2]
+  const proc = modules.unified().use(modules.remarkParse).use(modules.remarkSlug)
+  const tree = proc.runSync(proc.parse(before))
+  const head = tree.children[0]
+  assert(head && head.type === 'heading', 'expected `' + before + '` to be a heading, is it using a normal space after `#`?')
+  const autoId = head.data.id
+  const existingId = match[4]
+  const id = existingId || autoId
+  // Ignore numbers:
+  const cleanExisting = existingId ? existingId.replace(/-\d+$/, '') : undefined
+  const cleanAuto = autoId.replace(/-\d+$/, '')
+
+  if (cleanExisting && cleanExisting !== cleanAuto) {
+    console.log('Note: heading `%s` has a different ID (`%s`) than what GH generates for it: `%s`:', before, existingId, autoId)
   }
-  const headingText = line.slice(line.indexOf(' ')).trim();
-  const headingLevel = line.slice(0, line.indexOf(' '));
-  return `${headingLevel} ${headingText} {#${slugger.slug(
-    stripLinks(headingText)
-  )}}`;
+
+  return match[1] + match[2] + ' {/*' + id + '*/}';
 }
 
 function addHeaderIDs(lines) {
@@ -66,14 +83,26 @@ function addHeaderIDs(lines) {
 
 const [path] = process.argv.slice(2);
 
-const files = walk(path);
-files.forEach((file) => {
-  if (!(file.endsWith('.md') || file.endsWith('.mdx'))) {
-    return;
-  }
+main()
+
+async function main() {
+  const [unifiedMod, remarkParseMod, remarkSlugMod] = await Promise.all([import('unified'), import('remark-parse'), import('remark-slug')])
+  const unified = unifiedMod.default
+  const remarkParse = remarkParseMod.default
+  const remarkSlug = remarkSlugMod.default
+  modules = {unified, remarkParse, remarkSlug}
 
-  const content = fs.readFileSync(file, 'utf8');
-  const lines = content.split('\n');
-  const updatedLines = addHeaderIDs(lines);
-  fs.writeFileSync(file, updatedLines.join('\n'));
-});
+  const files = walk(path);
+
+  files.forEach((file) => {
+    if (!(file.endsWith('.md') || file.endsWith('.mdx'))) {
+      return;
+    }
+
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    const updatedLines = addHeaderIDs(lines);
+    fs.writeFileSync(file, updatedLines.join('\n'));
+  });
+
+}

beta/src/pages/blog/2013/06/05/why-react.md

@@ -6,13 +6,13 @@ author: [petehunt]
 There are a lot of JavaScript MVC frameworks out there. Why did we build React
 and why would you want to use it?
 
-## React isn't an MVC framework. {#react-isnt-an-mvc-framework}
+## React isn't an MVC framework. {/*react-isnt-an-mvc-framework*/}
 
 React is a library for building composable user interfaces. It encourages
 the creation of reusable UI components which present data that changes over
 time.
 
-## React doesn't use templates. {#react-doesnt-use-templates}
+## React doesn't use templates. {/*react-doesnt-use-templates*/}
 
 Traditionally, web application UIs are built using templates or HTML directives.
 These templates dictate the full set of abstractions that you are allowed to use
@@ -33,7 +33,7 @@ to render views, which we see as an advantage over templates for a few reasons:
 We've also created [JSX](/docs/jsx-in-depth.html), an optional syntax
 extension, in case you prefer the readability of HTML to raw JavaScript.
 
-## Reactive updates are dead simple. {#reactive-updates-are-dead-simple}
+## Reactive updates are dead simple. {/*reactive-updates-are-dead-simple*/}
 
 React really shines when your data changes over time.
 
@@ -63,7 +63,7 @@ Because this re-render is so fast (around 1ms for TodoMVC), the developer
 doesn't need to explicitly specify data bindings. We've found this approach
 makes it easier to build apps.
 
-## HTML is just the beginning. {#html-is-just-the-beginning}
+## HTML is just the beginning. {/*html-is-just-the-beginning*/}
 
 Because React has its own lightweight representation of the document, we can do
 some pretty cool things with it:

beta/src/pages/blog/2013/06/12/community-roundup.md

@@ -5,7 +5,7 @@ author: [vjeux]
 
 React was open sourced two weeks ago and it's time for a little round-up of what has been going on.
 
-## Khan Academy Question Editor {#khan-academy-question-editor}
+## Khan Academy Question Editor {/*khan-academy-question-editor*/}
 
 It looks like [Sophie Alpert](http://sophiebits.com/) is the first person outside of Facebook and Instagram to push React code to production. We are very grateful for her contributions in form of pull requests, bug reports and presence on IRC ([#reactjs on Freenode](irc://chat.freenode.net/reactjs)). Sophie wrote about her experience using React:
 
@@ -17,7 +17,7 @@ It looks like [Sophie Alpert](http://sophiebits.com/) is the first person outsid
 >
 > [Read the full post...](http://sophiebits.com/2013/06/09/using-react-to-speed-up-khan-academy.html)
 
-## Pimp my Backbone.View (by replacing it with React) {#pimp-my-backboneview-by-replacing-it-with-react}
+## Pimp my Backbone.View (by replacing it with React) {/*pimp-my-backboneview-by-replacing-it-with-react*/}
 
 [Paul Seiffert](https://blog.mayflower.de/) wrote a blog post that explains how to integrate React into Backbone applications.
 
@@ -29,15 +29,15 @@ It looks like [Sophie Alpert](http://sophiebits.com/) is the first person outsid
 >
 > [Read the full post...](https://blog.mayflower.de/3937-Backbone-React.html)
 
-## Using facebook's React with require.js {#using-facebooks-react-with-requirejs}
+## Using facebook's React with require.js {/*using-facebooks-react-with-requirejs*/}
 
 [Mario Mueller](http://blog.xenji.com/) wrote a menu component in React and was able to easily integrate it with require.js, EventEmitter2 and bower.
 
 > I recently stumbled upon facebook's React library, which is a JavaScript library for building reusable frontend components. Even if this lib is only at version 0.3.x it behaves very stable, it is fast and is fun to code. I'm a big fan of require.js, so I tried to use React within the require.js eco system. It was not as hard as expected and here are some examples and some thoughts about it.
 >
 > [Read the full post...](http://blog.xenji.com/2013/06/facebooks-react-require-js.html)
 
-## Origins of React {#origins-of-react}
+## Origins of React {/*origins-of-react*/}
 
 [Pete Hunt](http://www.petehunt.net/blog/) explained what differentiates React from other JavaScript libraries in [a previous blog post](/blog/2013/06/05/why-react.html). [Lee Byron](http://leebyron.com/) gives another perspective on Quora:
 

beta/src/pages/blog/2013/06/19/community-roundup-2.md

@@ -5,7 +5,7 @@ author: [vjeux]
 
 Since the launch we have received a lot of feedback and are actively working on React 0.4. In the meantime, here are the highlights of this week.
 
-## Some quick thoughts on React {#some-quick-thoughts-on-react}
+## Some quick thoughts on React {/*some-quick-thoughts-on-react*/}
 
 [Andrew Greig](http://www.andrewgreig.com/) made a blog post that gives a high level description of what React is.
 
@@ -19,7 +19,7 @@ Since the launch we have received a lot of feedback and are actively working on
 >
 > [Read the full post...](http://www.andrewgreig.com/637/)
 
-## React and Socket.IO Chat Application {#react-and-socketio-chat-application}
+## React and Socket.IO Chat Application {/*react-and-socketio-chat-application*/}
 
 [Danial Khosravi](https://danialk.github.io/) made a real-time chat application that interacts with the back-end using Socket.IO.
 
@@ -29,7 +29,7 @@ Since the launch we have received a lot of feedback and are actively working on
 >
 > [Read the full post...](https://danialk.github.io/blog/2013/06/16/reactjs-and-socket-dot-io-chat-application/)
 
-## React and Other Frameworks {#react-and-other-frameworks}
+## React and Other Frameworks {/*react-and-other-frameworks*/}
 
 [Pete Hunt](http://www.petehunt.net/blog/) wrote an answer on Quora comparing React and Angular directives. At the end, he explains how you can make an Angular directive that is in fact being rendered with React.
 
@@ -41,7 +41,7 @@ Since the launch we have received a lot of feedback and are actively working on
 
 In the same vein, [Markov Twain](https://twitter.com/markov_twain/status/345702941845499906) re-implemented the examples on the front-page [with Ember](http://jsbin.com/azihiw/2/edit) and [Vlad Yazhbin](https://twitter.com/vla) re-implemented the tutorial [with Angular](http://jsfiddle.net/vla/Cdrse/).
 
-## Web Components: React & x-tags {#web-components-react--x-tags}
+## Web Components: React & x-tags {/*web-components-react--x-tags*/}
 
 Mozilla and Google are actively working on Web Components. [Vjeux](http://blog.vjeux.com/) wrote a proof of concept that shows how to implement them using React.
 
@@ -51,7 +51,7 @@ Mozilla and Google are actively working on Web Components. [Vjeux](http://blog.v
 >
 > [Read the full post...](http://blog.vjeux.com/2013/javascript/custom-components-react-x-tags.html)
 
-## React TodoMVC Example {#react-todomvc-example}
+## React TodoMVC Example {/*react-todomvc-example*/}
 
 [TodoMVC.com](http://todomvc.com/) is a website that collects various implementations of the same basic Todo app. [Pete Hunt](http://www.petehunt.net/blog/) wrote an idiomatic React version.
 
@@ -63,7 +63,7 @@ Mozilla and Google are actively working on Web Components. [Vjeux](http://blog.v
 >
 > [Read the source code...](https://github.com/tastejs/todomvc/tree/gh-pages/labs/architecture-examples/react)
 
-## JSX is not HTML {#jsx-is-not-html}
+## JSX is not HTML {/*jsx-is-not-html*/}
 
 Many of you pointed out differences between JSX and HTML. In order to clear up some confusion, we have added some documentation that covers the four main differences:
 

beta/src/pages/blog/2013/06/21/react-v0-3-3.md

@@ -5,16 +5,16 @@ author: [zpao]
 
 We have a ton of great stuff coming in v0.4, but in the meantime we're releasing v0.3.3. This release addresses some small issues people were having and simplifies our tools to make them easier to use.
 
-## react-tools {#react-tools}
+## react-tools {/*react-tools*/}
 
 - Upgrade Commoner so `require` statements are no longer relativized when passing through the transformer. This was a feature needed when building React, but doesn't translate well for other consumers of `bin/jsx`.
 - Upgraded our dependencies on Commoner and Recast so they use a different directory for their cache.
 - Freeze our esprima dependency.
 
-## React {#react}
+## React {/*react*/}
 
 - Allow reusing the same DOM node to render different components. e.g. `React.renderComponent(<div/>, domNode); React.renderComponent(<span/>, domNode);` will work now.
 
-## JSXTransformer {#jsxtransformer}
+## JSXTransformer {/*jsxtransformer*/}
 
 - Improved the in-browser transformer so that transformed scripts will execute in the expected scope. The allows components to be defined and used from separate files.

beta/src/pages/blog/2013/06/27/community-roundup-3.md

@@ -5,7 +5,7 @@ author: [vjeux]
 
 The highlight of this week is that an interaction-heavy app has been ported to React. React components are solving issues they had with nested views.
 
-## Moving From Backbone To React {#moving-from-backbone-to-react}
+## Moving From Backbone To React {/*moving-from-backbone-to-react*/}
 
 [Clay Allsopp](https://twitter.com/clayallsopp) successfully ported [Propeller](http://usepropeller.com/blog/posts/from-backbone-to-react/), a fairly big, interaction-heavy JavaScript app, to React.
 
@@ -17,7 +17,7 @@ The highlight of this week is that an interaction-heavy app has been ported to R
 >
 > [Read the full post...](http://usepropeller.com/blog/posts/from-backbone-to-react/)
 
-## Grunt Task for JSX {#grunt-task-for-jsx}
+## Grunt Task for JSX {/*grunt-task-for-jsx*/}
 
 [Eric Clemmons](https://ericclemmons.github.io/) wrote a task for [Grunt](http://gruntjs.com/) that applies the JSX transformation to your JavaScript files. It also works with [Browserify](http://browserify.org/) if you want all your files to be concatenated and minified together.
 
@@ -45,7 +45,7 @@ The highlight of this week is that an interaction-heavy app has been ported to R
 >
 > [Check out the project ...](https://github.com/ericclemmons/grunt-react)
 
-## Backbone/Handlebars Nested Views {#backbonehandlebars-nested-views}
+## Backbone/Handlebars Nested Views {/*backbonehandlebars-nested-views*/}
 
 [Joel Burget](http://joelburget.com/) wrote a blog post talking about the way we would write React-like components in Backbone and Handlebars.
 
@@ -57,13 +57,13 @@ The highlight of this week is that an interaction-heavy app has been ported to R
 >
 > [Read the full post...](http://joelburget.com/react/)
 
-## JSRomandie Meetup {#jsromandie-meetup}
+## JSRomandie Meetup {/*jsromandie-meetup*/}
 
 [Renault John Lecoultre](https://twitter.com/renajohn/) from [BugBuster](http://www.bugbuster.com) did a React introduction talk at a JS meetup called [JS Romandie](https://twitter.com/jsromandie) last week.
 
 <script async class="speakerdeck-embed" data-id="888a9d50c01b01300df36658d0894ac1" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>
 
-## CoffeeScript integration {#coffeescript-integration}
+## CoffeeScript integration {/*coffeescript-integration*/}
 
 [Vjeux](http://blog.vjeux.com/) used the fact that JSX is just a syntactic sugar on-top of regular JS to rewrite the React front-page examples in CoffeeScript.
 
@@ -81,7 +81,7 @@ The highlight of this week is that an interaction-heavy app has been ported to R
 >
 > [Read the full post...](http://blog.vjeux.com/2013/javascript/react-coffeescript.html)
 
-## Tutorial in Plain JavaScript {#tutorial-in-plain-javascript}
+## Tutorial in Plain JavaScript {/*tutorial-in-plain-javascript*/}
 
 We've seen a lot of people comparing React with various frameworks. [Ricardo Tomasi](http://ricardo.cc/) decided to re-implement the tutorial without any framework, just plain JavaScript.
 

beta/src/pages/blog/2013/07/02/react-v0-4-autobind-by-default.md

@@ -6,7 +6,7 @@ author: [zpao]
 React v0.4 is very close to completion. As we finish it off, we'd like to share with you some of the major changes we've made since v0.3. This is the first of several posts we'll be making over the next week.
 
 
-## What is React.autoBind? {#what-is-reactautobind}
+## What is React.autoBind? {/*what-is-reactautobind*/}
 
 If you take a look at most of our current examples, you'll see us using `React.autoBind` for event handlers. This is used in place of `Function.prototype.bind`. Remember that in JS, [function calls are late-bound](https://bonsaiden.github.io/JavaScript-Garden/#function.this). That means that if you simply pass a function around, the `this` used inside won't necessarily be the `this` you expect. `Function.prototype.bind` creates a new, properly bound, function so that when called, `this` is exactly what you expect it to be.
 
@@ -33,7 +33,7 @@ React.createClass({
 ```
 
 
-## What's Changing in v0.4? {#whats-changing-in-v04}
+## What's Changing in v0.4? {/*whats-changing-in-v04*/}
 
 After using `React.autoBind` for a few weeks, we realized that there were very few times that we didn't want that behavior. So we made it the default! Now all methods defined within `React.createClass` will already be bound to the correct instance.
 

beta/src/pages/blog/2013/07/03/community-roundup-4.md

@@ -5,7 +5,7 @@ author: [vjeux]
 
 React reconciliation process appears to be very well suited to implement a text editor with a live preview as people at Khan Academy show us.
 
-## Khan Academy {#khan-academy}
+## Khan Academy {/*khan-academy*/}
 
 [Ben Kamens](http://bjk5.com/) explains how [Sophie Alpert](http://sophiebits.com/) and [Joel Burget](http://joelburget.com/) are promoting React inside of [Khan Academy](https://www.khanacademy.org/). They now have three projects in the works using React.
 
@@ -21,7 +21,7 @@ The best part is the demo of how React reconciliation process makes live editing
 
 [![](/images/blog/monkeys.gif)](http://bjk5.com/post/53742233351/getting-your-team-to-adopt-new-technology)
 
-## React Snippets {#react-snippets}
+## React Snippets {/*react-snippets*/}
 
 Over the past several weeks, members of our team, [Pete Hunt](http://www.petehunt.net/) and [Paul O'Shannessy](http://zpao.com/), answered many questions that were asked in the [React group](https://groups.google.com/forum/#!forum/reactjs). They give a good overview of how to integrate React with other libraries and APIs through the use of [Mixins](/docs/reusable-components.html) and [Lifecycle Methods](/docs/working-with-the-browser.html).
 
@@ -44,13 +44,13 @@ Over the past several weeks, members of our team, [Pete Hunt](http://www.petehun
 >
 > - [JSFiddle](http://jsfiddle.net/LQxy7/): Your React component simply render empty divs, and then in componentDidMount() you call React.renderComponent() on each of those divs to set up a new root React tree. Be sure to explicitly unmountAndReleaseReactRootNode() for each component in componentWillUnmount().
 
-## Introduction to React Screencast {#introduction-to-react-screencast}
+## Introduction to React Screencast {/*introduction-to-react-screencast*/}
 
 [Pete Hunt](http://www.petehunt.net/) recorded himself implementing a simple `<Blink>` tag in React.
 
 <figure><iframe src="https://player.vimeo.com/video/67248575" width="100%" height="340" frameborder="0" webkitAllowFullScreen mozallowfullscreen allowFullScreen></iframe></figure>
 
-## Snake in React {#snake-in-react}
+## Snake in React {/*snake-in-react*/}
 
 [Tom Occhino](http://tomocchino.com/) implemented Snake in 150 lines with React.