mdx-go：⚡️闪电般快速基于MDX的开发服务器

Node.js 其它杂项

访问GitHub主页

共328Star

详细介绍

mdx-go

⚡️ Lightning fast MDX-based dev server

npm i -g mdx-go

0️⃣ Zero-config dev server
📝 Write in markdown
⚛️ Import and use React components
📁 File-system based routing
📐 Customizable layouts
👩‍🎤 Support for styled-components & emotion
🌐 Export as static HTML

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

Using MDX

MDX combines the simplicity of markdown with the expressiveness of JSX. MDX lets you import and use React components inline with markdown docs.

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 MDXProvider in a Root component.

// example Root component
import React from 'react'
import { MDXProvider } from '@mdx-js/tag'

const components = {
  h1: props => <h1 {...props} style={{ fontSize: 48 }} />,
}

export const Root = props =>
  <MDXProvider components={components}>
    {props.children}
  </MDXProvider>

Ensure the Root component is exported from index.mdx

export { Root } from './Root.js'

Theming

Wrap MDX with a Root components and use the MDXProvider to change the default styles. For an out-of-the box solution, see mdx-themes.

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

All CLI options can also be specified in a mdx-go field in your package.json.