|
1 | | -# gatsby-gitbook-starter |
2 | | - |
3 | | -Kick off your project with this starter to create a powerful/flexible docs/tutorial web apps. |
4 | | - |
5 | | - |
6 | | - |
7 | | -## Motivation |
8 | | - |
9 | | -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. |
10 | | - |
11 | | -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. |
12 | | - |
13 | | -## 🔥 Features |
14 | | -- Write using Markdown / [MDX](https://github.com/mdx-js/mdx) |
15 | | -- GitBook style theme |
16 | | -- Syntax Highlighting using Prism [`Bonus`: Code diff highlighting] |
17 | | -- Google Analytics Integration |
18 | | -- Automatically generated sidebar navigation, table of contents, previous/next |
19 | | -- Edit on Github |
20 | | -- Fully customisable |
21 | | -- Rich embeds and live code editor using MDX |
22 | | -- Easy deployment: Deploy on Netlify / Now.sh / Docker |
23 | | - |
24 | | -## 🔗 Live Demo |
25 | | - |
26 | | -Here's a [live demo](https://learn.hasura.io/graphql/react) |
27 | | - |
28 | | -## 🚀 Quickstart |
29 | | - |
30 | | -Get started by running the following commands: |
31 | | - |
32 | | -``` |
33 | | -$ git clone [email protected]:hasura/gatsby-gitbook-starter.git |
34 | | -$ npm install |
35 | | -$ npm start |
36 | | -``` |
37 | | - |
38 | | -Visit `http://localhost:8000/` to view the app. |
39 | | - |
40 | | -## 🔧 Configure |
41 | | - |
42 | | -Write markdown files in `content` folder. |
43 | | - |
44 | | -Open `config.js` for templating variables. Broadly configuration is available for `gatsby`, `header`, `sidebar` and `siteMetadata`. |
45 | | - |
46 | | -- `gatsby` config for global configuration like |
47 | | - - `pathPrefix` - Gatsby Path Prefix |
48 | | - - `siteUrl` - Gatsby Site URL |
49 | | - - `gaTrackingId` - Google Analytics Tracking ID |
50 | | - |
51 | | -- `header` config for site header configuration like |
52 | | - - `title` - The title that appears on the top left |
53 | | - - `githubUrl` - The Github URL for the docs website |
54 | | - - `helpUrl` - Help URL for pointing to resources |
55 | | - - `tweetText` - Tweet text |
56 | | - - `links` - Links on the top right |
57 | | - |
58 | | -- `sidebar` config for navigation links configuration |
59 | | - - `forcedNavOrder` for left sidebar navigation order. It should be in the format "/<filename>" |
60 | | - - `links` - Links on the bottom left of the sidebar |
61 | | - |
62 | | -- `siteMetadata` config for website related configuration |
63 | | - - `title` - Title of the website |
64 | | - - `description` - Description of the website |
65 | | - - `ogImage` - Social Media share og:image tag |
66 | | - - `docsLocation` - The Github URL for Edit on Github |
67 | | - |
68 | | -- 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. |
69 | | - |
70 | | -## Live Code Editor |
71 | | - |
72 | | -To render react components for live editing, add the `react-live=true` to the code section. For example: |
73 | | - |
74 | | -```javascript react-live=true |
75 | | -<button>Edit my text</button> |
76 | | -``` |
77 | | - |
78 | | -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. |
79 | | - |
80 | | -## 🤖 SEO friendly |
81 | | - |
82 | | -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 |
83 | | - |
84 | | -```markdown |
85 | | ---- |
86 | | -title: "Title of the page" |
87 | | -metaTitle: "Meta Title Tag for this page" |
88 | | -metaDescription: "Meta Description Tag for this page" |
89 | | ---- |
90 | | -``` |
91 | | - |
92 | | -Canonical URLs are generated automatically. |
93 | | - |
94 | | -## ☁️ Deploy |
95 | | - |
96 | | -[](https://app.netlify.com/start/deploy?repository=https://github.com/hasura/gatsby-gitbook-starter) |
97 | | - |
| 1 | +This repo is still a bit of a mess....cleaning it up over the next few days. Stay tuned. |
0 commit comments