Home

Awesome

gatsby-gitbook-starter

Kick off your project with this starter to create a powerful/flexible docs/tutorial web apps.

gatsby-gitbook-starter

Motivation

We wanted to create a GraphQL tutorial series. The content would be written by developers for various languages/frameworks and what better than writing it in Markdown! And since this is a tutorial series we also needed rich embeds, syntax highlighting and more customisations.

We also wanted to serve these tutorials in sub paths of learn.hasura.io. To serve all these requirements, we decided to use Gatsby + MDX (Markdown + JSX) to extend markdown and used a neat consistent theme like the one at GitBook and deployed as docker containers.

🔥 Features

🔗 Live Demo

Here's a live demo

🚀 Quickstart

Get started by running the following commands:

$ git clone git@github.com:hasura/gatsby-gitbook-starter.git
$ cd gatsby-gitbook-starter
$ npm install
$ npm start

Visit http://localhost:8000/ to view the app.

🔧 Configure

Write markdown files in content folder.

Open config.js for templating variables. Broadly configuration is available for gatsby, header, sidebar and siteMetadata.

Algolia Configuration

To setup Algolia, go to config.js and update the search object to look like the one below:

	"search": {
		"enabled": true,
		"indexName": "MY_INDEX_NAME",
		"algoliaAppId": process.env.GATSBY_ALGOLIA_APP_ID,
		"algoliaSearchKey": process.env.GATSBY_ALGOLIA_SEARCH_KEY,
		"algoliaAdminKey": process.env.ALGOLIA_ADMIN_KEY
	},

Values for Algolia App ID, Search Key, and Admin Key can be obtained from Algolia Dashboard with the right set of permissions. Replace MY_INDEX_NAME with the Algolia Index name of your choice. To build the Algolia index, you need to run npm run build which will do a gatsby build along with content indexing in Algolia.

Progressive Web App, Offline

To enable PWA, go to config.js and update the pwa object to look like the one below:

   "pwa": {
        "enabled": false, // disabling this will also remove the existing service worker.
        "manifest": {
            "name": "Gatsby Gitbook Starter",
            "short_name": "GitbookStarter",
            "start_url": "/",
            "background_color": "#6b37bf",
            "theme_color": "#6b37bf",
            "display": "standalone",
            "crossOrigin": "use-credentials",
            icons: [
                {
                    src: "src/pwa-512.png",
                    sizes: `512x512`,
                    type: `image/png`,
                },
            ],
        },
    }

Live Code Editor

To render react components for live editing, add the react-live=true to the code section. For example:

<button>Edit my text</button>

In the above code, just add javascript react-live=true after the triple quote ``` to start rendering react components that can be edited by users.

🤖 SEO friendly

This is a static site and comes with all the SEO benefits. Configure meta tags like title and description for each markdown file using MDX Frontmatter

---
title: "Title of the page"
metaTitle: "Meta Title Tag for this page"
metaDescription: "Meta Description Tag for this page"
---

Canonical URLs are generated automatically.

☁️ Deploy

Deploy to Netlify