⚡ Lightning fast MDX-based dev server for progressive documentation
npm i -g mdx-go- 0️⃣ Zero-config dev server
- 📝 Write in markdown
- ⚛️ Import and use React components
- 📁 File-system based routing
- 📐 Customizable layouts
- 🌐 Export as static HTML
- 👩🎤 Support for styled-components & emotion
- 🔓 Avoid lock-in and easily migrate to other MDX-based tools
Create a docs folder and docs/index.mdx file.
import MyComponent from '../src'
# Component Demo
<MyComponent
beep='boop'
/>Start the dev server on the docs folder:
mdx-go docsAlternatively, mdx-go can be installed as a development dependency and used with run scripts in your package.json.
"scripts": {
"dev": "mdx-go docs",
"docs": "mdx-go build docs"
}npm run devmdx-go is built with the idea of Progressive Documentation in mind, intended to be used anywhere as a dev server, prototyping tool, or simple static site generator. By embracing the MDX file format, the docs you create with mdx-go can easily be used in other tools. Start your docs with mdx-go and migrate to tools like Next.js and Gatsby when needed. You can even keep mdx-go around to use as a dev tool outside of other React applications.
MDX combines the simplicity of markdown with the ability to import and use React components inline.
Write markdown like you normally would.
# HelloImport and use React components inline.
import { Box } from 'grid-styled'
# Hello
<Box p={3} bg='tomato'>
This is a React component!
</Box>To learn more about using MDX, see the MDX docs.
Each MDX file in the target directory will become its own route,
with index.mdx serving as the base route, i.e. /.
With the following directory structure:
docs/
index.mdx
getting-started.mdx
api.mdx
mdx-go will create routes for /, /getting-started, and /api.
mdx-go also supports using React components as routes for files with the .js extension.
Be sure that the .js file exports a default component to render as a route.
mdx-go includes a default layout that centers the document in the viewport, but custom layout components can be added both globally and per-route.
To render a custom layout for a single route, export a component as the default from the MDX file.
This is a built-in feature of MDX.
import Layout from './Layout'
export default Layout
# Page with layoutTo wrap all routes with a custom layout, export a Root component from your index.mdx file.
This will completely disable the built-in centered layout.
Note: this only works in the index route, not other routes.
export { Root } from './Root'
# Root layout for all routesHead contents can be set per-route by using the Head component.
import { Head } from 'mdx-go'
<Head>
<title>Page title</title>
</Head>
# Page with titleTo set head contents for all routes, use the Head component within a Root component.
To customize the HTML components rendered from MDX, use the ComponentProvider in a Root component.
// example Root component
import React from 'react'
import { ComponentProvider } from 'mdx-go'
const components = {
h1: props => <h1 {...props} style={{ fontSize: 48 }} />,
}
export const Root = props =>
<ComponentProvider components={components}>
{props.children}
</ComponentProvider>Ensure the Root component is exported from index.mdx
export { Root } from './Root.js'To specify a custom file pattern for matching against,
export a files webpack context from the main index.mdx file.
export const files = require.context('../src', true, /\.example\.js$/, 'lazy')By default mdx-go includes virtually no styling. To customize the styles, use components to wrap MDX with a Root component and use the MDXProvider to change the default styles.
To export as a static site with HTML and JS bundles, run:
mdx-go build docsThis will export all routes as HTML in a dist folder.
See CLI Options for configuration options.
mdx-go does not use any CSS-in-JS libraries internally, and most libraries will work when using the dev server.
To extract static CSS when using the build command, ensure you have either styled-components or emotion installed locally in your package.json.
For Emotion, be sure that emotion-server is also installed.
When either of these libraries are detected in your package.json dependencies, mdx-go will extract static CSS during the build process.
The following flags can be passed to the CLI.
-p --port Port for dev server
--no-open Disable opening in default browser
-d --out-dir Output directory for static export
--basename Base path for routing
--static Export HTML without JS bundle
--webpack Path to custom webpack config
All CLI options can also be specified in a mdx-go field in your package.json.
"mdx-go": {
"outDir": "site"
}mdx-go will automatically pick up a webpack.config.js if it exists in the current working directory.
A custom path can be passed to the CLI using the --webpack flag.
The provided webpack config will be merged with the built-in config using webpack-merge.
MDX | mdx-deck | mdx-docs | ok-mdx | x0
