chore(docs): allow to use .mdx format in docs

CHANGELOG.md

@@ -127,6 +127,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Add theme switcher for exploring different themes on the docs (only available in development mode) @mnajdova ([#280](https://github.com/stardust-ui/react/pull/280))
 - Add `Prototypes` section and `Chat Pane` prototype (only available in development mode) @Bugaa92 ([#235](https://github.com/stardust-ui/react/pull/235))
 - Remove cruft prop `suiVersion` from the `ComponentExample` component @layershifter ([#329](https://github.com/stardust-ui/react/pull/329))
+- Add the ability to use .mdx files in documentation @layershifter ([#330](https://github.com/stardust-ui/react/pull/330))
 
 <!--------------------------------[ v0.8.0 ]------------------------------- -->
 ## [v0.8.0](https://github.com/stardust-ui/react/tree/v0.8.0) (2018-10-01)

docs/src/components/MarkdownProvider/MarkdownProvider.tsx

@@ -0,0 +1,10 @@
+import * as React from 'react'
+import { MDXProvider } from '@mdx-js/tag'
+
+import components from './components'
+
+const MarkdownProvider = ({ children }) => (
+  <MDXProvider components={components}>{children}</MDXProvider>
+)
+
+export default MarkdownProvider

docs/src/components/MarkdownProvider/components.tsx

@@ -0,0 +1,39 @@
+import _ from 'lodash'
+import * as React from 'react'
+import { Link } from 'react-router-dom'
+import { Header } from '@stardust-ui/react'
+
+import CodeSnippet from 'docs/src/components/CodeSnippet'
+
+// Heads up!
+// These functions are only component's mapping.
+
+const a = ({ children, href }) => {
+  const isExternal = _.startsWith(href, 'http://') || _.startsWith(href, 'https://')
+
+  return isExternal ? (
+    <a href={href} target="_blank" rel="noopener noreferrer">
+      {children}
+    </a>
+  ) : (
+    <Link to={href}>{children}</Link>
+  )
+}
+
+const code = ({ className, children, label }) => {
+  const mode = className && _.replace(className, 'language-', '')
+  const value = _.trim(children)
+
+  return <CodeSnippet label={label} mode={mode} value={value} />
+}
+
+const h1 = ({ children }) => <Header as="h1" content={children} />
+
+const h2 = ({ children }) => <Header as="h2" content={children} />
+
+export default {
+  a,
+  code,
+  h1,
+  h2,
+}

docs/src/components/MarkdownProvider/index.ts

@@ -0,0 +1,2 @@
+export { default } from './MarkdownProvider'
+export { default as renderPage } from './renderPage'

docs/src/components/MarkdownProvider/renderPage.tsx

@@ -0,0 +1,22 @@
+import * as React from 'react'
+import DocPage from 'docs/src/components/DocPage'
+
+type MarkdownPage = {
+  default: React.ComponentType<any>
+  meta: {
+    description?: string
+    title: string
+  }
+}
+
+const renderPage = (page: MarkdownPage) => () => {
+  const { default: Component, meta } = page
+
+  return (
+    <DocPage {...meta}>
+      <Component />
+    </DocPage>
+  )
+}
+
+export default renderPage

docs/src/routes.tsx

@@ -4,12 +4,13 @@ import { BrowserRouter, Route, Switch } from 'react-router-dom'
 import ExternalExampleLayout from './components/ExternalExampleLayout'
 import DocsLayout from './components/DocsLayout'
 import DocsRoot from './components/DocsRoot'
+import MarkdownProvider, { renderPage } from './components/MarkdownProvider'
 
 import Accessibility from './views/Accessibility'
 import ShorthandProps from './views/ShorthandProps'
 import Introduction from './views/Introduction'
 import PageNotFound from './views/PageNotFound'
-import QuickStart from './views/QuickStart'
+import * as QuickStart from './views/QuickStart.md'
 import Theming from './views/Theming'
 import ThemingExamples from './views/ThemingExamples'
 
@@ -20,7 +21,7 @@ const Router = () => (
       <Switch>
         <DocsLayout exact path="/" component={Introduction} />
         <DocsLayout exact path="/:type/:name" component={DocsRoot} sidebar />
-        <DocsLayout exact path="/quick-start" component={QuickStart} />
+
         {process.env.NODE_ENV !== 'production' && [
           <DocsLayout
             exact
@@ -53,10 +54,16 @@ const Router = () => (
             component={require('./prototypes/SearchPage/index').default}
           />,
         ]}
+
         <DocsLayout exact path="/accessibility" component={Accessibility} />
         <DocsLayout exact path="/theming" component={Theming} />
         <DocsLayout exact path="/theming-examples" component={ThemingExamples} />
         <DocsLayout exact path="/shorthand-props" component={ShorthandProps} />
+
+        <MarkdownProvider>
+          <DocsLayout exact path="/quick-start" component={renderPage(QuickStart)} />
+        </MarkdownProvider>
+
         <DocsLayout exact path="/*" component={PageNotFound} />
       </Switch>
     </Switch>

docs/src/views/QuickStart.md

@@ -0,0 +1,60 @@
+import { NavLink } from 'react-router-dom'
+import { Button, Divider } from '@stardust-ui/react'
+
+export const meta = {
+  title: 'Quick Start',
+}
+
+## Install
+
+Stardust UI should be installed as a `dependency` of your app.
+
+```sh
+yarn add @stardust-ui/react
+```
+
+## Setup
+
+Stardust components are styled using CSS in JS. This technique requires a style renderer to
+render JavaScript objects to CSS. [React Context](https://reactjs.org/docs/context.html) is used to provide the style
+renderer and theme to components.
+
+Place a `<Provider />` at the root of your app and pass theme as props.
+
+```jsx label=index.jsx
+import React from 'react'
+import ReactDOM from 'react-dom'
+import { Provider, themes } from '@stardust-ui/react'
+
+import App from './App'
+
+ReactDOM.render(
+  <Provider theme={themes.teams}>
+    <App />
+  </Provider>,
+  document.getElementById('root'),
+)
+```
+
+## Usage
+
+That's it. You can now use Stardust UI components in your app.
+
+```jsx label=App.jsx
+import React from 'react'
+import { Button } from '@stardust-ui/react'
+
+export default () => <Button content="Theming" icon="arrow right" iconPosition="after" primary />
+```
+
+<Divider />
+<br />
+
+<Button
+  as={NavLink}
+  content="Accessibility"
+  icon="arrow right"
+  iconPosition="after"
+  primary
+  to="accessibility"
+/>

package.json

@@ -44,6 +44,10 @@
       "prettier --write",
       "tslint -t stylish --fix",
       "git add"
+    ],
+    "**/*.md": [
+      "prettier --parser mdx --write",
+      "git add"
     ]
   },
   "repository": {
@@ -96,6 +100,10 @@
     "what-input": "^5.1.2"
   },
   "devDependencies": {
+    "@babel/core": "^7.1.2",
+    "@babel/plugin-proposal-object-rest-spread": "^7.0.0",
+    "@babel/preset-react": "^7.0.0",
+    "@mdx-js/loader": "^0.15.5",
     "@types/classnames": "^2.2.4",
     "@types/enzyme": "^3.1.14",
     "@types/faker": "^4.1.3",
@@ -107,6 +115,7 @@
     "@types/react-dom": "^16.0.6",
     "@types/react-router": "^4.0.27",
     "awesome-typescript-loader": "4.0.1",
+    "babel-loader": "^8.0.4",
     "connect-history-api-fallback": "^1.3.0",
     "copy-to-clipboard": "^3.0.8",
     "copy-webpack-plugin": "^4.5.2",
@@ -140,7 +149,7 @@
     "lint-staged": "^7.0.2",
     "merge2": "^1.2.2",
     "normalize.css": "^8.0.0",
-    "prettier": "1.12.0",
+    "prettier": "^1.15.1",
     "raw-loader": "^0.5.1",
     "react": "^16.0.0",
     "react-ace": "^5.1.2",

types/global.d.ts

@@ -14,3 +14,14 @@ declare module '*.json' {
   const value: any
   export default value
 }
+
+declare module '*.md' {
+  const MDXComponent: React.ComponentType<any>
+
+  export const meta: {
+    description?: string
+    title: string
+  }
+
+  export default MDXComponent
+}

webpack.config.ts

@@ -1,8 +1,8 @@
+import { CheckerPlugin as AsyncTypeScriptChecker } from 'awesome-typescript-loader'
 import * as CopyWebpackPlugin from 'copy-webpack-plugin'
 import * as HtmlWebpackPlugin from 'html-webpack-plugin'
 import * as _ from 'lodash'
 import * as webpack from 'webpack'
-import { CheckerPlugin as AsyncTypeScriptChecker } from 'awesome-typescript-loader'
 
 import config from './config'
 
@@ -50,6 +50,20 @@ const webpackConfig: any = {
           errorsAsWarnings: __DEV__,
         },
       },
+      {
+        test: /\.md$/,
+        exclude: /node_modules/,
+        use: [
+          {
+            loader: 'babel-loader',
+            options: {
+              presets: ['@babel/preset-react'],
+              plugins: ['@babel/plugin-proposal-object-rest-spread'],
+            },
+          },
+          '@mdx-js/loader',
+        ],
+      },
     ],
   },
   plugins: [