33

gatsby-gitbook-starter: Build responsive modern documentation websites using MDX

 4 years ago
source link: https://www.tuicool.com/articles/RJjQRvv
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

gatsby-gitbook-starter

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

miIBv2U.png!web

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.

:fire: Features

  • Write using Markdown / MDX
  • GitBook style theme
  • Syntax Highlighting using Prism [ Bonus : Code diff highlighting]
  • Google Analytics Integration
  • Automatically generated sidebar navigation, table of contents, previous/next
  • Edit on Github
  • Fully customisable
  • Rich embeds using MDX
  • Easy deployment: Deploy on Netlify / Now.sh / Docker

:link: Live Demo

Here's a live demo

:rocket: Quickstart

Get started by running the following commands:

$ git clone [email protected]:hasura/gatsby-gitbook-starter.git
$ npm install
$ npm start

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

:wrench: Configure

Write markdown files in content folder.

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

  • gatsby config for global configuration like 

    pathPrefix
siteUrl
gaTrackingId

  • header config for site header configuration like 

    title
githubUrl
helpUrl
tweetText
links

  • sidebar config for navigation links configuration 

    forcedNavOrder
links

  • siteMetadata config for website related configuration 

    title
description
ogImage
docsLocation

  • For sub nesting in left sidebar, create a folder with the same name as the top level .md filename and the sub navigation is auto-generated. Currently it supports only one level of nesting. The sub navigation is alphabetically ordered.

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.

:cloud: Deploy


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK