Creating a minimalist docs site with Gatsby and MDX

Good open source projects need great docs, so I’ve built a Gatsby Theme to make it quick to get up and running with a minimal docs site.

I’ve given it the completely uncreative name gatsby-theme-documentation.

Below will walk through turning a directory of Markdown/MDX files into a full-fledged docs site (that even looks nice).

Scaffolding

gatsby new new-docs johno/gatsby-starter-documentation
cd new-docs

Now, copy in your directory of Markdown/MDX files:

rm -rf docs
mv ../docs docs

Then, run the server to render your docs pages:

yarn start

Change the sidebar

You’ll likely notice that the sidebar navigation isn’t correct for your newly created docs. In order to change them you can write a Markdown list at src/gatsby-theme-documentation/sidebar.mdx:

- [Introduction](/)
- [Tutorial](/tutorial)
- [Getting Started](/getting-started)
- [Contributing](/contributing)
- [FAQ](/faq)

Update the heading information

You can also update the header data and links by changing src/gatsby-theme-documentation/header.mdx.

# ![Docs Logo](https://contrast.now.sh/white/black?width=80&height=40&text=NEWDOCS)

[GitHub](https://github.com/my/repo)
[Twitter](https://twitter.com/my-twitter)

Change the theme tokens

Then, if you want to change some color in your theme or even things like the font family or font size, open up src/gatsby-theme-documentation/theme.js and watch any changes hot reload in front of you.

Conclusion

If you want to only write MDX and get a docs site running quickly without having to do much design, gatsby-theme-documentation is a great way to do that.

Acknowledgements

The majority of the code in this theme was originally written by Brent Jackson. I mostly just converted it to a theme and added header/sidebar shadowing.

Related

If you have a need for more complex features or are building a design system, it’s recommended to check out Docz. It’s a more feature-rich project that comes with batteries included.