• This repository has been archived on 31/Jan/2023
  • Stars
    star
    362
  • Rank 117,671 (Top 3 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created about 6 years ago
  • Updated almost 5 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

⚡ Lightning fast MDX-based dev server for progressive documentation

mdx-go

⚡ Lightning fast MDX-based dev server for progressive documentation

https://mdx-go.now.sh

Build Status Downloads Version MIT License

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

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

Related

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

MIT License


More Repositories

1

mdx-deck

♠️ React MDX-based presentation decks
JavaScript
11,314
star
2

loading

This could take a while
CSS
3,531
star
3

colorable

Color combination contrast tester
HTML
1,958
star
4

reflexbox

Moved to https://rebassjs.org
JavaScript
1,354
star
5

fitter-happier-text

Performant, fully fluid headings
HTML
1,291
star
6

repng

React component to PNG converter
JavaScript
890
star
7

palx

🌈 Automatic UI Color Palette Generator
JavaScript
838
star
8

geomicons-open

Open Source Icons for the Web
HTML
832
star
9

ok-mdx

Browser-based MDX editor
JavaScript
761
star
10

ram

⚛️ React Application Manager: create and run React (and other) applications – no command line or build setup required
JavaScript
585
star
11

react-x-ray

React CSS Layout Debugger
JavaScript
571
star
12

macro-components

Create flexible layout and composite UI components without the need to define arbitrary custom props
JavaScript
485
star
13

plangular

Create custom SoundCloud players with HTML & CSS
HTML
485
star
14

shade

Gradient explorer
HTML
460
star
15

mdx-docs

📝 Document and develop React components with MDX and Next.js
JavaScript
451
star
16

paths

Build and edit SVGs in the browser
JavaScript
418
star
17

tachyons-components

React UI components powered by Tachyons with a styled-components like API
JavaScript
411
star
18

microicon

SVG icon microservice
JavaScript
359
star
19

static-react

Zero-configuration CLI React static renderer
JavaScript
350
star
20

reline

React SVG line icon components
JavaScript
247
star
21

react-css-grid

React layout component based on CSS Grid Layout and built with styled-components
JavaScript
241
star
22

refunk

🎧 Simple React functional setState
JavaScript
236
star
23

hello-color

JavaScript
231
star
24

gravitons

JavaScript
218
star
25

layouts

Grab-and-go layouts for React
JavaScript
215
star
26

contrast-swatch

🅰️ Image microservice for color contrast information
JavaScript
209
star
27

axs

Stupid simple style components for React
JavaScript
209
star
28

rgx

React grid system based on minimum and maximum widths
JavaScript
202
star
29

nano-component

Fast & simple React component styles in under 1kb
JavaScript
196
star
30

mdx-blocks

JavaScript
191
star
31

vhs

Post-Future CSS Animations
HTML
184
star
32

papercraft

Hand-coded SVG lettering
CSS
153
star
33

blog

Personal blog on design & development
HTML
146
star
34

figma-theme

Generate development-ready theme JSON files from Figma Styles
JavaScript
137
star
35

react-icons

Building SVG Icons with React
HTML
134
star
36

system-components

https://github.com/jxnblk/styled-system/tree/master/system-components
JavaScript
131
star
37

Heather

A HyperMinimal Jekyll Theme
CSS
129
star
38

rmdi

React Material Design Icons – built with Pixo, Styled Components, and Styled System
JavaScript
129
star
39

geomicons-wired

Geometric Icons
CSS
125
star
40

react-static-site-boilerplate

Demo boilerplate for generating a static site with React
HTML
115
star
41

rebranch

React context-based, conditional rendering components for A/B experiments
JavaScript
107
star
42

Ashley

A Readable & Responsive Theme for Tumblr
CSS
106
star
43

ejsx

Pure JSX templates for rendering static HTML
JavaScript
105
star
44

superbox

DEPRECATED: See https://rebassjs.org/reflexbox instead
JavaScript
102
star
45

live-doc

💫 Convert markdown to live React demos
JavaScript
99
star
46

gatsby-themes

JavaScript
97
star
47

Twipster

CSS
95
star
48

css-to-object

JavaScript
92
star
49

dropbar

JavaScript
88
star
50

react-geomicons

React icon component for Geomicons Open
JavaScript
88
star
51

nano-style

React functional CSS-in-JS
JavaScript
84
star
52

horror

😱 React HTML elements with CSS-in-JS
JavaScript
78
star
53

SoundRad

A Radically Simpler & Faster SoundCloud Player
JavaScript
77
star
54

rebass-recomposed

JavaScript
77
star
55

Spectral

Click the Rainbow
JavaScript
74
star
56

skullcat

a avatar fur mrmrs
JavaScript
73
star
57

_gx

DEPRECATED Minimal responsive React grid system based on the Fab Four Technique.
HTML
73
star
58

vim-mdx-js

Vim Script
73
star
59

stepkit

JavaScript
72
star
60

bumpkit

JavaScript
70
star
61

rrx

⚛️ Minimal React router using higher order components
JavaScript
69
star
62

type-system

HTML
66
star
63

f0

JavaScript
65
star
64

understyle

Functional style utilities for authoring JavaScript style objects
JavaScript
60
star
65

gatsby-theme-mdx-blog

JavaScript
58
star
66

microbeats

Beats Created in Under an Hour
JavaScript
56
star
67

hypercolors

Generative hyperterm color theme
JavaScript
55
star
68

react-cxs

ϟ Alternative React.createElement function which allows style objects to be passed to the className prop to generate CSS
JavaScript
55
star
69

formula

CSS calculator for bulletproof form and button styles that always line up
JavaScript
51
star
70

reaxe

🍬 Syntactic sugar for React.createElement and JSX alternative
JavaScript
51
star
71

tempo

Responsive Grid System
CSS
48
star
72

diet-cola

A lightweight styled-components clone for creating React UI component primitives.
JavaScript
48
star
73

hyperterminator

Hyperterm theme for cybernetic organisms
JavaScript
47
star
74

react-fitter-happier-text

React component for fully fluid headings
JavaScript
46
star
75

css-scss

Convert CSS syntax to SCSS with calc, variables, and custom media queries
JavaScript
44
star
76

react-owl

🦉 React layout component based on the lobotomized owl selector and built with styled-components
JavaScript
42
star
77

robox

Higher-order React component for adding style helper props based on understyle
JavaScript
41
star
78

monochrome

JavaScript
40
star
79

hyp

ϟ Functional UI component microlibrary with ES6 tagged template literals
JavaScript
39
star
80

superstyle

CSSOM-JS utility library
JavaScript
39
star
81

universal-components

JavaScript
38
star
82

scrs

JavaScript
38
star
83

hidden-styled

JavaScript
37
star
84

grays

HTML
35
star
85

colorable-app

Color constrast checker
JavaScript
34
star
86

principles

My principles of web design
HTML
33
star
87

object-style

JavaScript
33
star
88

redeck

DEPRECATED: see https://github.com/jxnblk/mdx-deck
JavaScript
32
star
89

react-component-permutations

Uses propTypes to create an array of React component props to display various permutations.
HTML
32
star
90

tag-hoc

React HOC to set an element's tag and remove props
JavaScript
31
star
91

cxs-components

Styled UI component primitives for React - built with cxs
JavaScript
31
star
92

kenburns

Sass mixin for Ken Burns effect background images
CSS
30
star
93

json-react

JavaScript
30
star
94

react-media-context

React higher-order component (HOC) to provide context for the currently matched media query.
JavaScript
30
star
95

watch

In case you forget what time it is
JavaScript
30
star
96

react-simple-icons

JavaScript
29
star
97

path-ast

SVG path element command parser/stringifier
JavaScript
29
star
98

simple-modular-scale

Modular scale generator based on an array of ratios
JavaScript
29
star
99

typography-system

JavaScript
28
star
100

mdx-themes

JavaScript
26
star