https://github.com/tomitrescak/torydocs
https://github.com/tomitrescak/torydocs
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/tomitrescak/torydocs
- Owner: tomitrescak
- License: mit
- Created: 2019-07-01T07:53:04.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-11T20:42:14.000Z (over 2 years ago)
- Last Synced: 2025-02-07T19:34:57.219Z (4 months ago)
- Language: JavaScript
- Size: 1.61 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gatsby-gitbook-starter
Kick off your project with this starter to create a powerful/flexible docs/tutorial web apps.
## Motivation
We wanted to create a [GraphQL tutorial](https://learn.hasura.io) 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](https://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](https://www.gitbook.com) and deployed as docker containers.
## 🔥 Features
- Write using Markdown / [MDX](https://github.com/mdx-js/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 and live code editor using MDX
- Easy deployment: Deploy on Netlify / Now.sh / Docker
## 🔗 Live Demo
Here's a [live demo](https://learn.hasura.io/graphql/react)
## 🚀 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.
## 🔧 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` - Gatsby Path Prefix
- `siteUrl` - Gatsby Site URL
- `gaTrackingId` - Google Analytics Tracking ID
- `header` config 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
- `sidebar` config for navigation links configuration
- `forcedNavOrder` for left sidebar navigation order. It should be in the format "/"
- `links` - Links on the bottom left of the sidebar
- `siteMetadata` config 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 `.md` filename and the sub navigation is auto-generated. Currently it supports only one level of nesting. 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:
```javascript react-live=true
Edit my text
```
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
```markdown
---
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
[](https://app.netlify.com/start/deploy?repository=https://github.com/hasura/gatsby-gitbook-starter)