Docs-as-code Starter Kit

You can use this repository as a starting point to manage your documentation as code.

This docs-as-code example is built on top of Gatsby.js and is part of a tutorial posted on Medium:

How we switched to documentation-as-code with Gatsby.js and Netlify — part 1/2

Getting started

Run the following commands in your CLI to serve your website locally.

git clone git@github.com:squadlytics/docs-as-code-starterkit.git
cd docs-as-code-starterkit
npm install
gatsby develop

You should be able to go to http://localhost:8000/ and see the docs homepage.

Editing the docs

All the docs are written in Markdown in /src/docs. You can edit the existing pages or create new one with the following process:

Create a new Markdown file in /src/docs/, for instance /src/docs/mydoc.md.
Add a Front Matter at the top of your doc.
Make sure that the Front Matter contains the path and title of your doc. The path is how people will get access to the page.
Write your doc in Markdown format and save it.
Go to http://localhost:8000/<path_of_the_doc> to view it in your browser.

Adding Mixpanel and DocSearch

You can add Mixpanel tracking and search via DocSearch (you'll need to sign up first) by defining environment variables in your dev environment and in your build configuration when deploying to production.

Here's below a template for a dev environment set up using a .env.development file that you should put at the root of the repository.

#.env.development
GATSBY_MIXPANEL_KEY=<your Mixpanel key>
GATSBY_DOCSEARCH_API_KEY=<your DocSearch API Key>
GATSBY_DOCSEARCH_INDEX=<your DocSearch index reference>

Check https://www.gatsbyjs.org/docs/environment-variables/ to know more about setting up environment variables.

Deploying

You can easily deploy your docs for free with Netlify. Check out the tutorial if you want a step by step guide.

Contributing