mdx-go

:zap: Lightning fast MDX-based dev server for progressive documentation

https://mdx-go.now.sh

npm i -g mdx-go

:zero: Zero-config dev server
:memo: Write in markdown
:atom_symbol: Import and use React components
:file_folder: File-system based routing
:triangular_ruler: Customizable layouts
:globe_with_meridians: Export as static HTML
:woman_singer: Support for styled-components & emotion
:unlock: Avoid lock-in and easily migrate to other MDX-based tools

Getting Started

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 docs

npm run scripts

Alternatively, 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 dev

Motivation

mdx-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.

Using MDX

MDX combines the simplicity of markdown with the ability to import and use React components inline.

Write markdown like you normally would.

# Hello

Import 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.

Routing

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.

Layouts

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 layout

To 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 routes

Head Content

Head contents can be set per-route by using the Head component.

import { Head } from 'mdx-go'

<Head>
  <title>Page title</title>
</Head>

# Page with title

To set head contents for all routes, use the Head component within a Root component.

Custom MDX Components

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'

Custom File Match Pattern

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')

Theming

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.

Exporting

To export as a static site with HTML and JS bundles, run:

mdx-go build docs

This will export all routes as HTML in a dist folder. See CLI Options for configuration options.

CSS-in-JS

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.

CLI Options

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"
}

Custom webpack config

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.

Examples

MDX | mdx-deck | mdx-docs | ok-mdx | x0

MIT License

jxnblk / mdx-go

readme