Kick off your project with this starter to create a powerful/flexible docs/tutorial web apps.
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.
- Write using Markdown / MDX
- GitBook style theme
- Syntax Highlighting using Prism [
Bonus: Code diff highlighting]
- Search Integration with Algolia
- Google Analytics Integration
- Automatically generated sidebar navigation, table of contents, previous/next
- Edit on Github
- Fully customisable
- Rich embeds and live code editor using MDX
- Easy deployment: Deploy on Netlify / Now.sh / Docker
🔗 Live Demo
Here's a live demo
Get started by running the following commands:
$ git clone email@example.com:hasura/gatsby-gitbook-starter.git $ npm install $ npm start
http://localhost:8000/ to view the app.
Write markdown files in
config.js for templating variables. Broadly configuration is available for
gatsbyconfig for global configuration like
pathPrefix- Gatsby Path Prefix
siteUrl- Gatsby Site URL
gaTrackingId- Google Analytics Tracking ID
headerconfig for site header configuration like
title- The title that appears on the top left
githubUrl- The Github URL for the docs website
helpUrl- Help URL for pointing to resources
tweetText- Tweet text
links- Links on the top right
search- Enable search and configure Algolia
sidebarconfig for navigation links configuration
forcedNavOrderfor left sidebar navigation order. It should be in the format "/"
frontLine- whether to show a front line at the beginning of a nested menu.(Collapsing capability would be turned of if this option is set to true)
links- Links on the bottom left of the sidebar
ignoreIndex- Set this to true if the index.md file shouldn't appear on the left sidebar navigation. Typically this can be used for landing pages.
siteMetadataconfig for website related configuration
title- Title of the website
description- Description of the website
ogImage- Social Media share og:image tag
docsLocation- The Github URL for Edit on Github
For sub nesting in left sidebar, create a folder with the same name as the top level
.mdfilename and the sub navigation is auto-generated. The sub navigation is alphabetically ordered.
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
🤖 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.