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 t

Setting Up Docs For An Open Source Project Doesn't Have To Be Hard

submited by
Style Pass
2021-05-26 20:00:11

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.

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 docs 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).

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.

Leave a Comment