A practical guide to set up Jekyll + Github Pages for docs This article describes how we set up docs for our open source project Saasform. Docs are part of the , so they're browsable and easy to maintain. Moreover, by using Jekyll + Github Pages, they're automatically deployed at . source code docs.saasform.dev In short, here's how it works: Create docs with Jekyll, in a folder right in the repo docs Use a remote theme, like pmarsceill/just-the-docs Publish via Github Pages In the rest of the article we'll detail each step. Create Docs via Jekyll Github has great docs to get started with Jekyll and Github Pages, mostly centered around publishing a blog. I followed to create a new Jekyll project in the folder and made sure I could test it locally. Then I set the theme. this guide docs just-the-docs 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. one can consume the docs in the right order even just browsing the code on Github. Pro: I had to specify the URL of each individual page. A bit tedious but worth for SEO. Con: I recommend taking a look at a to see if you like this structure. few examples Use a Remote Theme 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. remote_theme: pmarsceill/just-the-docs 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. Publish via Github Pages To publish the docs: Set the domain docs.<domain> as a CNAME to <org-name>.github.io, e.g. in my case . docs.saasform.dev -> CNAME saasform.github.io Enable Github Pages in the repo settings. 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!

Google

Secure Sessions in JavaScript: Forking Express-Session to Improve Security

Security, Obscurity, Openness

Join my NFT project: Everdragons2

Nominated for 2022 - HackerNoon Contributor of the Year - Finance

Too Long; Didn't Read

Make resilience your competitive advantage

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

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

NFT Taxes for Dummies: Everything You Need to Know to Get Started

10 Knowledge Base Software Best Practice Examples

5 reasons to ditch the paper and start document automation

5 Software Documentation Tools That Make Managing Technical Documentation Easier

6 Ways Digital Document Management Will Empower Your Business

NFT Taxes for Dummies: Everything You Need to Know to Get Started

10 Knowledge Base Software Best Practice Examples

5 reasons to ditch the paper and start document automation

5 Software Documentation Tools That Make Managing Technical Documentation Easier

6 Ways Digital Document Management Will Empower Your Business

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps