Co-founder at Saasform, SoloKeys. Former security at Pinterest.
This article describes how we set up docs for our open source project Saasform. Docs are part of the source code, so they're browsable and easy to maintain. Moreover, by using Jekyll + Github Pages, they're automatically deployed at docs.saasform.dev.
In short, here's how it works:
folder right in the repo
In the rest of the article we'll detail each step.
Github has great docs to get started with Jekyll and Github Pages, mostly centered around publishing a blog. I followed this guide to create a new Jekyll project in the
folder and made sure I could test it locally. Then I set the just-the-docs theme.
Next, I structured the docs. I used a Google doc to organize the content in sections and subsections. I find it very convenient to see the big picture and exchange comments with my teammates.
Then it time to create the docs files... it's just a pretty tedious task (I wish there was a better way to export from gdoc to md).
After some back and forth I decided to name all files and folders starting with a number.
I recommend taking a look at a few examples to see if you like this structure.
At this point I committed my changes and published to Github Pages. Soon after I received an automated email "Page build warning" from Github as the theme I chose isn't supported.
The solution turns out to be incredibly simple: instead of "theme: just-the-docs", specify
. That's it.
I went through all the themes supported by Github Pages and they all look for blogs. If anyone at Github is reading this, perhaps you can consider adding a few themes for docs too.
To publish the docs:
docs.saasform.dev -> CNAME saasform.github.io
It may take a few minutes before the pages are built and the HTTPS certificate is created. After that, anytime you commit to your repo the docs will get automatically updated.
We've seen how to structure docs as part of the source code, so they're browsable, easy to maintain and automatically deployed.
If you end up using this structure, please let me know. Happy to take a look at what you made!
Create your free account to unlock your custom reading experience.