How to Use Your README.md on Your Project’s Docs Page

Originally published on Aug 23, 2020

You have a project. You want to make a Docs Page. You already wrote documentation in

README.md

. Do you need to have two copies of your ReadMe? Heck no!

Let’s start by cloning the Next.js MDX example. Note, you could do this same thing with Gatsby, Create React App or anything that supports MDX.

npx create-next-app --example with-mdx with-mdx-app

Next, we create a page at

pages/docs.js

. Using MDXProvider, we can import

README.md

and drop it on the page.

import { MDXProvider } from "@mdx-js/react"
import ReadMe from "../README.md"

const Docs = () => (
  <MDXProvider>
    <ReadMe />
  </MDXProvider>
)

export default Docs

npm run dev

, go to

localhost:3000/docs

and there’s your README content.

Do a

vercel deploy

, hit return/enter a bunch of times and your docs page is live. See for example readme-as-project-docs.vercel.app/docs