mdx-go
v2.0.0-32
Published
Lightning-fast MDX-based dev server
Downloads
480
Maintainers
jxnblkReadme
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 docsnpm 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 devMotivation
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.
# 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.
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.mdxmdx-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 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 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 titleTo 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 docsThis 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 configAll 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
Related
MDX | mdx-deck | mdx-docs | ok-mdx | x0