docs(v2): embedding real source code in MDX as a code block

website/package.json

@@ -50,5 +50,8 @@
       "last 1 firefox version",
       "last 1 safari version"
     ]
+  },
+  "devDependencies": {
+    "raw-loader": "^4.0.1"
   }
 }

website/src/pages/examples/_myComponent.js

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+export default function MyComponent() {
+  const [bool, setBool] = React.useState(false);
+  return (
+    <div>
+      <p>MyComponent rendered !</p>
+      <p>bool={bool ? 'true' : 'false'}</p>
+      <p>
+        <button onClick={() => setBool((b) => !b)}>toggle bool</button>
+      </p>
+    </div>
+  );
+}

website/src/pages/examples/markdownPageExample.md

@@ -61,3 +61,65 @@ import Chapter1 from './\_chapter1.md';
 import Chapter2 from './\_chapter2.mdx';
 
 <Chapter2/>
+
+## Comments
+
+MDX comments can be used with
+
+```mdx
+<!--
+
+My comment
+
+-->
+```
+
+See, nothing is displayed:
+
+<!--
+
+My comment
+
+-->
+
+## Import code block from source code file
+
+import MyComponent from "./\_myComponent"
+
+import BrowserWindow from '@site/src/components/BrowserWindow';
+
+Let's say you have a React component.
+
+You can import and use it in MDX:
+
+```jsx title="myMarkdownFile.mdx"
+import MyComponent from './myComponent';
+
+<MyComponent />;
+```
+
+<BrowserWindow url="http://localhost:3000">
+
+<MyComponent/>
+
+</BrowserWindow>
+
+But you can also display its source code directly in MDX, thanks to [Webpack raw-loader](https://webpack.js.org/loaders/raw-loader/)
+
+```jsx title="myMarkdownFile.mdx"
+import CodeBlock from '@theme/CodeBlock';
+
+import MyComponentSource from '!!raw-loader!./myComponent';
+
+<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>;
+```
+
+import CodeBlock from "@theme/CodeBlock"
+
+import MyComponentSource from '!!raw-loader!./\_myComponent';
+
+<BrowserWindow url="http://localhost:3000">
+
+<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>
+
+</BrowserWindow>

yarn.lock

@@ -17595,6 +17595,14 @@ raw-body@~1.1.0:
     bytes "1"
     string_decoder "0.10"
 
+raw-loader@^4.0.1:
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/raw-loader/-/raw-loader-4.0.1.tgz#14e1f726a359b68437e183d5a5b7d33a3eba6933"
+  integrity sha512-baolhQBSi3iNh1cglJjA0mYzga+wePk7vdEX//1dTFd+v4TsQlQE0jitJSNF1OIP82rdYulH7otaVmdlDaJ64A==
+  dependencies:
+    loader-utils "^2.0.0"
+    schema-utils "^2.6.5"
+
 rc@^1.0.1, rc@^1.1.6, rc@^1.2.7, rc@^1.2.8:
   version "1.2.8"
   resolved "https://registry.yarnpkg.com/rc/-/rc-1.2.8.tgz#cd924bf5200a075b83c188cd6b9e211b7fc0d3ed"