{"id":13788319,"url":"https://github.com/jxnblk/mdx-go","last_synced_at":"2025-09-27T01:30:50.602Z","repository":{"id":67375989,"uuid":"146111022","full_name":"jxnblk/mdx-go","owner":"jxnblk","description":":zap: Lightning fast MDX-based dev server for progressive documentation","archived":true,"fork":false,"pushed_at":"2020-01-16T16:25:36.000Z","size":1557,"stargazers_count":362,"open_issues_count":10,"forks_count":28,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-09-20T09:02:02.454Z","etag":null,"topics":["design","design-systems","development","documentation","isolated","js","markdown","mdx","react","style-guide","testing","ui","zero-config"],"latest_commit_sha":null,"homepage":"https://mdx-go.now.sh","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jxnblk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-08-25T16:23:54.000Z","updated_at":"2024-06-01T10:19:22.000Z","dependencies_parsed_at":"2023-05-12T10:15:32.655Z","dependency_job_id":null,"html_url":"https://github.com/jxnblk/mdx-go","commit_stats":null,"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmdx-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmdx-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmdx-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jxnblk%2Fmdx-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jxnblk","download_url":"https://codeload.github.com/jxnblk/mdx-go/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219871825,"owners_count":16554457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design","design-systems","development","documentation","isolated","js","markdown","mdx","react","style-guide","testing","ui","zero-config"],"created_at":"2024-08-03T21:00:43.508Z","updated_at":"2025-09-27T01:30:45.280Z","avatar_url":"https://github.com/jxnblk.png","language":"JavaScript","funding_links":[],"categories":["Projects","Site Generators","JavaScript"],"sub_categories":[],"readme":"\n# mdx-go\n\n![](https://s3.amazonaws.com/jxnblk/mdx-go-24.gif)\n\n:zap: Lightning fast [MDX][]-based dev server for progressive documentation\n\nhttps://mdx-go.now.sh\n\n[![Build Status][badge]][travis]\n[![Downloads][downloads-badge]][npm]\n[![Version][version-badge]][npm]\n[![MIT License][license]](LICENSE.md)\n\n```sh\nnpm i -g mdx-go\n```\n\n- :zero: Zero-config dev server\n- :memo: Write in markdown\n- :atom_symbol: Import and use React components\n- :file_folder: File-system based routing\n- :triangular_ruler: Customizable layouts\n- :globe_with_meridians: Export as static HTML\n- :woman_singer: Support for [styled-components][] \u0026 [emotion][]\n- :unlock: Avoid lock-in and easily migrate to other MDX-based tools\n\n[badge]: https://flat.badgen.net/travis/jxnblk/mdx-go\n[travis]: https://travis-ci.org/jxnblk/mdx-go\n\n[version-badge]: https://flat.badgen.net/npm/v/mdx-go\n[downloads-badge]: https://flat.badgen.net/npm/dt/mdx-go\n[npm]: https://npmjs.com/package/mdx-go\n\n[license]: https://flat.badgen.net/badge/license/MIT/blue\n[coverage]: https://flat.badgen.net/codecov/c/github/jxnblk/mdx-go\n\n## Getting Started\n\nCreate a `docs` folder and `docs/index.mdx` file.\n\n```mdx\nimport MyComponent from '../src'\n\n# Component Demo\n\n\u003cMyComponent\n  beep='boop'\n/\u003e\n```\n\nStart the dev server on the `docs` folder:\n\n```sh\nmdx-go docs\n```\n\n### npm run scripts\n\nAlternatively, mdx-go can be installed as a development dependency and used with run scripts in your `package.json`.\n\n```json\n\"scripts\": {\n  \"dev\": \"mdx-go docs\",\n  \"docs\": \"mdx-go build docs\"\n}\n```\n\n```sh\nnpm run dev\n```\n\n## Motivation\n\nmdx-go is built with the idea of **[Progressive Documentation][]** in mind,\nintended to be used anywhere as a dev server, prototyping tool, or simple static site generator.\nBy embracing the MDX file format, the docs you create with mdx-go can easily be used in other tools.\nStart your docs with mdx-go and migrate to tools like [Next.js][] and [Gatsby][] when needed.\nYou can even keep mdx-go around to use as a dev tool outside of other React applications.\n\n[Next.js]: https://github.com/zeit/next.js/\n[Gatsby]: https://github.com/gatsbyjs/gatsby\n\n## Using MDX\n\nMDX combines the simplicity of markdown with the ability to import and use React components inline.\n\nWrite markdown like you normally would.\n\n```md\n# Hello\n```\n\nImport and use React components inline.\n\n```mdx\nimport { Box } from 'grid-styled'\n\n# Hello\n\n\u003cBox p={3} bg='tomato'\u003e\n  This is a React component!\n\u003c/Box\u003e\n```\n\nTo learn more about using MDX, see the [MDX docs][MDX].\n\n## Routing\n\nEach MDX file in the target directory will become its own route,\nwith `index.mdx` serving as the base route, i.e. `/`.\n\nWith the following directory structure:\n\n```\ndocs/\n  index.mdx\n  getting-started.mdx\n  api.mdx\n```\n\nmdx-go will create routes for `/`, `/getting-started`, and `/api`.\n\nmdx-go also supports using React components as routes for files with the `.js` extension.\nBe sure that the `.js` file exports a default component to render as a route.\n\n## Layouts\n\nmdx-go includes a default layout that centers the document in the viewport,\nbut custom layout components can be added both globally and per-route.\n\nTo render a custom layout for a single route, export a component as the `default` from the MDX file.\nThis is a built-in [feature of MDX](https://mdxjs.com/syntax#export-default).\n\n```mdx\nimport Layout from './Layout'\n\nexport default Layout\n\n# Page with layout\n```\n\nTo wrap all routes with a custom layout, export a `Root` component from your `index.mdx` file.\nThis will completely disable the built-in centered layout.\nNote: this only works in the `index` route, not other routes.\n\n```mdx\nexport { Root } from './Root'\n\n# Root layout for all routes\n```\n\n## Head Content\n\nHead contents can be set per-route by using the `Head` component.\n\n```mdx\nimport { Head } from 'mdx-go'\n\n\u003cHead\u003e\n  \u003ctitle\u003ePage title\u003c/title\u003e\n\u003c/Head\u003e\n\n# Page with title\n```\n\nTo set head contents for all routes, use the Head component within a [`Root` component](#layouts).\n\n## Custom MDX Components\n\nTo customize the HTML components rendered from MDX, use the `ComponentProvider` in a [`Root` component](#layouts).\n\n```js\n// example Root component\nimport React from 'react'\nimport { ComponentProvider } from 'mdx-go'\n\nconst components = {\n  h1: props =\u003e \u003ch1 {...props} style={{ fontSize: 48 }} /\u003e,\n}\n\nexport const Root = props =\u003e\n  \u003cComponentProvider components={components}\u003e\n    {props.children}\n  \u003c/ComponentProvider\u003e\n```\n\nEnsure the Root component is exported from `index.mdx`\n\n```mdx\nexport { Root } from './Root.js'\n```\n\n## Custom File Match Pattern\n\nTo specify a custom file pattern for matching against,\nexport a `files` webpack context from the main `index.mdx` file.\n\n```mdx\nexport const files = require.context('../src', true, /\\.example\\.js$/, 'lazy')\n```\n\n## Theming\n\nBy default mdx-go includes virtually no styling. To customize the styles, use components to\nwrap MDX with a [Root component](#layouts) and use the [MDXProvider](#custom-mdx-components) to change the default styles.\n\n## Exporting\n\nTo export as a static site with HTML and JS bundles, run:\n\n```sh\nmdx-go build docs\n```\n\nThis will export all routes as HTML in a `dist` folder.\nSee [CLI Options](#cli-options) for configuration options.\n\n## CSS-in-JS\n\nmdx-go does not use any CSS-in-JS libraries internally, and most libraries will work when using the dev server.\nTo extract static CSS when using the `build` command, ensure you have either `styled-components` or `emotion` installed locally in your `package.json`.\nFor Emotion, be sure that `emotion-server` is also installed.\n\nWhen either of these libraries are detected in your `package.json` dependencies, mdx-go will extract static CSS during the build process.\n\n## CLI Options\n\nThe following flags can be passed to the CLI.\n\n```\n  -p --port     Port for dev server\n  --no-open     Disable opening in default browser\n  -d --out-dir  Output directory for static export\n  --basename    Base path for routing\n  --static      Export HTML without JS bundle\n  --webpack     Path to custom webpack config\n```\n\nAll CLI options can also be specified in a `mdx-go` field in your `package.json`.\n\n```json\n\"mdx-go\": {\n  \"outDir\": \"site\"\n}\n```\n\n## Custom webpack config\n\nmdx-go will automatically pick up a `webpack.config.js` if it exists in the current working directory.\nA custom path can be passed to the CLI using the `--webpack` flag.\nThe provided webpack config will be merged with the built-in config using [webpack-merge][].\n\n[webpack-merge]: https://github.com/survivejs/webpack-merge\n\n\n## Examples\n\n- [Basic](examples/basic)\n- [Head Content](examples/head-content)\n- [Routing](examples/routing)\n- [Styled Components](examples/styled-components)\n- [Emotion](examples/emotion)\n- [Dev Environment](examples/dev-environment)\n- [React Live](examples/react-live)\n\n\n## Related\n\n[MDX][] | [mdx-deck][] | [mdx-docs][] | [ok-mdx][] |\n[x0][]\n\n\n[MIT License](LICENSE.md)\n\n---\n\n\u003cp align='center'\u003e\n  \u003cimg src='docs/src/logo.png' width='64' height='64' /\u003e\n\u003c/p\u003e\n\n\n[MDX]: https://github.com/mdx-js/mdx\n[mdx-themes]: https://github.com/jxnblk/mdx-themes\n[mdx-deck]: https://github.com/jxnblk/mdx-deck\n[mdx-docs]: https://github.com/jxnblk/mdx-docs\n[ok-mdx]: https://github.com/jxnblk/ok-mdx\n[styled-components]: https://github.com/styled-components/styled-components\n[emotion]: https://github.com/emotion-js/emotion\n[x0]: https://github.com/c8r/x0\n[Progressive Documentation]: https://jxnblk.com/blog/progressive-documentation/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjxnblk%2Fmdx-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjxnblk%2Fmdx-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjxnblk%2Fmdx-go/lists"}