├── .gitignore ├── .travis.yml ├── CHANGELOG.md ├── Dockerfile ├── LICENSE.md ├── README.md ├── babel.config.js ├── docs ├── .gitignore ├── README.md ├── babel.config.js ├── next.config.js ├── package-lock.json ├── package.json ├── pages │ ├── _app.js │ ├── _document.js │ ├── components.md │ ├── custom-setup.md │ ├── exporting.md │ ├── getting-started.md │ ├── index.md │ ├── migrating-from-x0.md │ ├── theming.md │ └── typography.mdx ├── src │ ├── card.js │ └── components.js └── static │ ├── card.png │ └── mdx-docs.gif ├── lerna.json ├── now.json ├── package-lock.json ├── package.json ├── packages ├── create-docs │ ├── README.md │ ├── cli.js │ ├── package-lock.json │ └── package.json ├── mdx-docs │ ├── .npmignore │ ├── README.md │ ├── babel.config.js │ ├── package-lock.json │ ├── package.json │ └── src │ │ ├── Layout.js │ │ ├── NavLinks.js │ │ ├── Pagination.js │ │ ├── components.js │ │ ├── context.js │ │ ├── index.js │ │ └── withComponents.js ├── mdx-live │ ├── .npmignore │ ├── README.md │ ├── babel.config.js │ ├── docs │ │ └── index.mdx │ ├── package-lock.json │ ├── package.json │ ├── src │ │ └── index.js │ └── test │ │ ├── __snapshots__ │ │ └── index.js.snap │ │ └── index.js ├── mdx-style │ ├── .npmignore │ ├── README.md │ ├── babel.config.js │ ├── package-lock.json │ ├── package.json │ ├── src │ │ ├── index.js │ │ └── themes │ │ │ ├── base.js │ │ │ ├── index.js │ │ │ └── term.js │ ├── test │ │ ├── __fixtures__ │ │ │ └── hello.mdx │ │ ├── __snapshots__ │ │ │ └── index.js.snap │ │ └── index.js │ └── themes.js └── next-mdx-docs │ ├── README.md │ ├── index.js │ ├── package-lock.json │ └── package.json └── templates └── next ├── .gitignore ├── README.md ├── next.config.js ├── package-lock.json ├── package.json └── pages ├── _app.js ├── _document.js ├── components ├── Button.md └── index.md ├── getting-started.md └── index.md /.gitignore: -------------------------------------------------------------------------------- 1 | dist 2 | coverage 3 | node_modules 4 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | node_js: 3 | - 10 4 | before_deploy: 5 | - cd docs 6 | - npm install 7 | - npm run build 8 | - touch out/.nojekyll 9 | deploy: 10 | provider: pages 11 | skip_cleanup: true 12 | github_token: $GH_TOKEN 13 | local_dir: docs/out 14 | on: 15 | branch: master 16 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | 2 | # Changelog 3 | 4 | ## Unreleased 5 | 6 | - Reorganized as monorepo 7 | - Added mdx-live package 8 | - Added mdx-style package 9 | - Update to Next.js 7 10 | - Update to Babel 7 11 | - Use links from MDXProvider 12 | - New Layout component API 13 | - Removes styled-components and emotion dependencies 14 | - Added `getRoute` prop for use outside of Next.js 15 | - Renamed `SideNav` to `NavLinks` 16 | - Removed `Header` component 17 | - Removed `Root` component 18 | - Removed `Container` component 19 | - Removed `LiveCode` component 20 | - Removed `MenuButton` component 21 | - Removed theming API 22 | 23 | ## v1.0.0-9 (2018-08-30) 24 | 25 | - Adds `active` className to NavLink 26 | 27 | ## v1.0.0-8 (2018-08-18) 28 | ## v1.0.0-7 (2018-08-18) 29 | ## v1.0.0-3 (2018-08-16) 30 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM node:10-alpine 2 | 3 | WORKDIR /usr/src 4 | 5 | COPY . . 6 | 7 | RUN npm i 8 | RUN npm run prepare 9 | RUN npm t 10 | 11 | RUN cd docs && npm i && npm run build && mv out /public 12 | 13 | COPY docs/static/* /public/ 14 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | 2 | # The MIT License (MIT) 3 | Copyright (c) 2018 Brent Jackson 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 | 11 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # MDX Docs 3 | 4 | :memo: Document and develop React components with [MDX][] and [Next.js][] 5 | 6 | ![](docs/static/mdx-docs.gif) 7 | 8 | https://mdx-docs.now.sh/ 9 | 10 | [![Build Status][badge]][travis] 11 | [![Downloads][downloads-badge]][npm] 12 | [![Version][version-badge]][npm] 13 | [![MIT License][license]](LICENSE.md) 14 | 15 | ```sh 16 | npm init docs 17 | ``` 18 | 19 | - :memo: Create documentation with markdown 20 | - :atom_symbol: Import and use React components 21 | - :gear: Component-based API 22 | - :computer: Live code examples 23 | - :nail_care: Customizable themes 24 | - ▲ Built for Next.js 25 | 26 | [badge]: https://flat.badgen.net/travis/jxnblk/mdx-docs 27 | [travis]: https://travis-ci.org/jxnblk/mdx-docs 28 | [version-badge]: https://flat.badgen.net/npm/v/mdx-docs 29 | [downloads-badge]: https://flat.badgen.net/npm/dt/mdx-docs 30 | [npm]: https://npmjs.com/package/mdx-docs 31 | [license]: https://flat.badgen.net/badge/license/MIT/blue 32 | 33 | ## Getting Started 34 | 35 | To create a new documentation site, run `npm init docs` and follow the prompts. 36 | Once the application has been generated, see the [README.md](templates/next/README.md) 37 | for more documentation. 38 | 39 | To add MDX Docs to an existing Next.js app, see the [Custom Setup](docs/pages/custom-setup.md) docs. 40 | 41 | ## Using MDX 42 | 43 | MDX lets you mix markdown with inline JSX to render React components. 44 | Write markdown as you normally would and use ES import syntax to use custom components in your document. 45 | 46 | ```mdx 47 | import { Box } from 'grid-styled' 48 | 49 | # Hello MDX! 50 | 51 | 54 | This will render as a component 55 | 56 | ``` 57 | 58 | ## Live Code 59 | 60 | MDX Docs has built-in components to render JSX fenced code blocks as live previews with editable code, powered by [react-live](https://github.com/FormidableLabs/react-live). 61 | To make a code block render as an editable example, use the `.jsx` language attribute (note the `.` prefix). 62 | 63 | ````mdx 64 | Live code example: 65 | 66 | ```.jsx 67 | 68 | ``` 69 | ```` 70 | 71 | [react-live]: https://github.com/FormidableLabs/react-live 72 | 73 | ## Components Scope 74 | 75 | To add components to scope for use in the live code examples, 76 | pass a `components` object to the [`Layout`](docs/pages/components.md#Layout) component. 77 | 78 | ```jsx 79 | // example components 80 | import React from 'react' 81 | 82 | export default { 83 | Box: props => ( 84 |
91 | ) 92 | } 93 | ``` 94 | 95 | ```jsx 96 | // example _app.js 97 | 100 | 101 | 102 | 103 | 104 | ``` 105 | 106 | The `components` object can also include components to render the HTML elements in MDX. 107 | 108 | 109 | ## Documentation 110 | 111 | - [Components](https://mdx-docs.now.sh/components) 112 | - [Custom Setup](https://mdx-docs.now.sh/custom-setup) 113 | 114 | --- 115 | 116 | #### Prior Art 117 | 118 | [mdx-go][], 119 | [Compositor x0][], 120 | [mdx-deck][], 121 | [live-doc][], 122 | [Doctor Mark][], 123 | [docz][] 124 | 125 | #### Related 126 | 127 | [Next.js][], 128 | [MDX][], 129 | [react-live](https://github.com/FormidableLabs/react-live) 130 | 131 | [mdx-go]: https://github.com/jxnblk/mdx-go 132 | [Compositor x0]: https://compositor.io/x0 133 | [live-doc]: https://github.com/jxnblk/live-doc 134 | [Doctor Mark]: https://github.com/jxnblk/doctor-mark 135 | [mdx-deck]: https://github.com/jxnblk/mdx-deck 136 | [docz]: https://github.com/pedronauck/docz 137 | 138 | [MDX]: https://github.com/mdx-js/mdx 139 | [Next.js]: https://github.com/zeit/next.js/ 140 | 141 | 142 | [MIT License](LICENSE.md) 143 | -------------------------------------------------------------------------------- /babel.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | presets: [ 3 | '@babel/env', 4 | '@babel/react', 5 | ], 6 | plugins: [ 7 | '@babel/proposal-class-properties', 8 | '@babel/proposal-export-namespace-from', 9 | ] 10 | } 11 | -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | npm-debug.log 3 | .next 4 | out 5 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | 2 | # mdx-docs 3 | 4 | This project was built with [mdx-docs][] and [Next.js][] 5 | 6 | ## Getting Started 7 | 8 | ```sh 9 | npm install 10 | ``` 11 | 12 | ### Run in development mode 13 | 14 | ```sh 15 | npm start 16 | ``` 17 | 18 | ### Export static site 19 | 20 | ```sh 21 | npm run build 22 | ``` 23 | 24 | ## Adding Routes & Navigation 25 | 26 | Each file in the `pages/` directory will create a route for your application. 27 | To edit the navigation in the sidebar, change the `routes` array in the [`pages/_app.js`](pages/_app.js) component. 28 | 29 | For more information on how Next.js works, see the [Next.js Docs][Next.js]. 30 | 31 | ## Customizing 32 | 33 | To customize the look at feel of your application see the docs for mdx-docs: 34 | 35 | - [Theming Docs][docs-theming] 36 | - [Components Docs][docs-components] 37 | 38 | Built with [mdx-docs][] 39 | 40 | [mdx-docs]: https://github.com/jxnblk/mdx-docs 41 | [Next.js]: https://github.com/zeit/next.js/ 42 | [docs-components]: https://github.com/jxnblk/mdx-docs/blob/master/docs/components.md 43 | [docs-theming]: https://github.com/jxnblk/mdx-docs/blob/master/docs/theming.md 44 | -------------------------------------------------------------------------------- /docs/babel.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | presets: [ 3 | 'next/babel' 4 | ], 5 | plugins: [ 6 | '@babel/proposal-export-namespace-from', 7 | 'babel-plugin-styled-components', 8 | ] 9 | } 10 | -------------------------------------------------------------------------------- /docs/next.config.js: -------------------------------------------------------------------------------- 1 | const path = require('path') 2 | const mdPlugins = [ 3 | require('remark-autolink-headings'), 4 | require('remark-emoji'), 5 | require('remark-images'), 6 | require('remark-slug'), 7 | require('remark-unwrap-images'), 8 | ] 9 | 10 | module.exports = { 11 | pageExtensions: [ 12 | 'js', 'md', 'mdx' 13 | ], 14 | webpack: (config, { defaultLoaders }) => { 15 | config.module.rules.push({ 16 | test: /\.js$/, 17 | exclude: /node_modules/, 18 | include: path.join(__dirname, '../packages'), 19 | use: [defaultLoaders.babel] 20 | }) 21 | 22 | config.module.rules.push({ 23 | test: /\.mdx?$/, 24 | use: [ 25 | defaultLoaders.babel, 26 | { 27 | loader: '@mdx-js/loader', 28 | options: { 29 | mdPlugins 30 | } 31 | } 32 | ] 33 | }) 34 | 35 | config.resolve.alias['styled-components'] = path.join(__dirname, './node_modules/styled-components') 36 | config.resolve.alias['@mdx-js/tag'] = path.join(__dirname, './node_modules/@mdx-js/tag') 37 | 38 | config.resolve.alias['mdx-docs'] = path.join(__dirname, '../packages/mdx-docs/src') 39 | config.resolve.alias['mdx-style'] = path.join(__dirname, '../packages/mdx-style/src') 40 | config.resolve.alias['mdx-live'] = path.join(__dirname, '../packages/mdx-live/src') 41 | 42 | return config 43 | }, 44 | } 45 | -------------------------------------------------------------------------------- /docs/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "scripts": { 4 | "start": "next", 5 | "build": "next build && next export", 6 | "card": "npx repng src/card.js -w 1024 -h 512 -d static -f card.png" 7 | }, 8 | "dependencies": { 9 | "@mdx-js/mdx": "^0.15.5", 10 | "@mdx-js/tag": "^0.15.0", 11 | "babel-loader": "^8.0.4", 12 | "babel-plugin-styled-components": "^1.8.0", 13 | "next": "^7.0.1", 14 | "prop-types": "^15.6.2", 15 | "react": "^16.5.2", 16 | "react-dom": "^16.5.2", 17 | "styled-components": "^3.4.9" 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /docs/pages/_app.js: -------------------------------------------------------------------------------- 1 | import React from 'react' 2 | import App, { Container } from 'next/app' 3 | import Head from 'next/head' 4 | import { 5 | Layout, 6 | SideNav, 7 | Pagination 8 | } from 'mdx-docs' 9 | import components from '../src/components' 10 | 11 | const routes = [ 12 | { name: 'MDX Docs', path: '/' }, 13 | { name: 'Theming', path: '/theming' }, 14 | { name: 'Components', path: '/components' }, 15 | { name: 'Custom Setup', path: '/custom-setup' }, 16 | { name: 'Migrating from x0', path: '/migrating-from-x0' }, 17 | { name: 'GitHub', path: 'https://github.com/jxnblk/mdx-docs' }, 18 | ] 19 | 20 | export default class MyApp extends App { 21 | static async getInitialProps ({ Component, router, ctx }) { 22 | let page = {} 23 | 24 | if (Component.getInitialProps) { 25 | page = await Component.getInitialProps(ctx) 26 | } 27 | 28 | return { page } 29 | } 30 | 31 | render () { 32 | const { Component, page } = this.props 33 | 34 | return ( 35 | 36 | 37 | MDX Docs 38 | 39 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | ) 54 | } 55 | } 56 | -------------------------------------------------------------------------------- /docs/pages/_document.js: -------------------------------------------------------------------------------- 1 | import Document, { Head, Main, NextScript } from 'next/document' 2 | import { ServerStyleSheet } from 'styled-components' 3 | 4 | const isProd = process.env.NODE_ENV === 'production' 5 | 6 | const BaseCSS = ({ css }) => 7 |