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).
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
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)
You can also update the header data and links by changing
src/gatsby-theme-documentation/header.mdx
.
# 
[GitHub](https://github.com/my/repo)
[Twitter](https://twitter.com/my-twitter)
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.
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.
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.
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.