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

Do 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