├── .gitignore ├── .prettierrc ├── LICENSE ├── README.md ├── gatsby-browser.js ├── gatsby-config.js ├── gatsby-node.js ├── gatsby-ssr.js ├── package-lock.json ├── package.json ├── src ├── components │ ├── header.js │ ├── layout.css │ ├── layout.js │ ├── propstable.js │ └── sidebar.js ├── images │ └── gatsby-icon.png ├── pages │ ├── 404.js │ ├── about.js │ ├── index.js │ └── page-2.js ├── templates │ ├── page-default.js │ └── posts.js └── tools │ └── capitalize.js ├── thumbnail.png └── thumbnail2.jpg /.gitignore: -------------------------------------------------------------------------------- 1 | # Project dependencies 2 | .cache 3 | node_modules 4 | yarn-error.log 5 | 6 | # Build directory 7 | /public 8 | .DS_Store 9 | -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "semi": false, 3 | "singleQuote": true, 4 | "trailingComma": "es5" 5 | } 6 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 gatsbyjs 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![Screenshot of example Documentation website created with this template](thumbnail.png) 2 | 3 | # Gatsby Documentation Starter 4 | 5 | Automatically generate documentation for your project using MDX, react-docgen, and GatsbyJS. 6 | 7 | ## Features 8 | 9 | - 📝 [MDX](https://github.com/mdx-js/mdx) - Write your documentation in Markdown and include React components using JSX! 10 | - ♻️ [react-docgen](https://github.com/reactjs/react-docgen) - Automatically parses all your React components (functional, stateful, even stateless!) for JS Docblocks and Prop Types. 11 | - ⚛️ [GatsbyJS](http://gatsby.org) - Creates local GraphQL server to build static version of documentation (easily deployed on a CDN or GHPages, Netlify, etc) 12 | - 🗄 Props Table - Component for displaying component props in a table format 13 | - 🎛 Modular - Easily install inside existing projects! 14 | - ⚖️ Lightweight - Only what you need, no extra dependencies. 15 | 16 | ## Quick Start 17 | 18 | **Install with Netlify** 19 | 20 | 1. [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/whoisryosuke/gatsby-documentation-starter/tree/example) 21 | 22 | 23 | **Install with Gatsby CLI** 24 | 25 | 1. `gatsby new docs https://github.com/whoisryosuke/gatsby-documentation-starter/` 26 | 27 | **Custom install** 28 | 29 | 1. `git clone https://github.com/whoisryosuke/gatsby-documentation-starter.git` 30 | 1. Update `gatsby-config.js` with the location of your components + MDX _(see: "Changing source folder")_ 31 | 1. `npm install` inside project 32 | 1. `npm run develop` 33 | 1. View your documentation: http://localhost:8000 34 | 35 | Check out the [example branch](https://github.com/whoisryosuke/gatsby-documentation-starter/tree/example) to see the source code of [the demo](https://gatsby-documentation-starter.netlify.com/). 36 | 37 | ### Creating documentation 38 | 39 | Documentation is sourced from two places: component source code and MDX files. 40 | 41 | ``` 42 | src 43 | └── components 44 | └── Button 45 | ├── Button.js 46 | └── Button.mdx 47 | ``` 48 | 49 | **React-docgen** grabs any JS Docblocks you write for your React classes/functions (`Button.js`), as well as the Prop Types. These are displayed on your documentation page, with the props displayed in a table. 50 | 51 | Inside your **MDX** file you can write additional documentation with JSX examples. You can also specify the page slug here (a **page name** and **category**). Your pages will be generated as `http://yoursite.com//`. 52 | 53 | In order for your component data to show up, you need an MDX file for the component - and the page name and component name in the docblock need to match. 54 | 55 | ```js 56 | /** 57 | * ComponentTitle 58 | **/ 59 | class ComponentName extends React.Component {} 60 | ``` 61 | 62 | ```md 63 | --- 64 | name: ComponentTitle 65 | menu: CategoryName 66 | --- 67 | ``` 68 | 69 | > Creates a page for the component located at http://localhost:8000/categoryname/componentname 70 | 71 | ## Documentation 72 | 73 | ## Customizing sidebar navigation 74 | 75 | The sidebar navigation is generated from two places: a JSON config with static pages, and component MDX files. The static pages are displayed before the components. 76 | 77 | To customize the static pages, go to `gatsby-config.js` and edit the `sidebar` object inside the `siteMetadata` config. Each page is represented as an object with a slug (the URL) and title: 78 | 79 | ```json 80 | siteMetadata: { 81 | title: 'Gatsby Documentation Starter', 82 | sidebar: { 83 | pages: [ 84 | { 85 | slug: '/about', 86 | title: 'about', 87 | }, 88 | ], 89 | }, 90 | }, 91 | ``` 92 | 93 | The component pages in the navigation are automatically generated by querying all components with MDX files. If you want to change this, see section: _"Creating pages from react-docgen"_ 94 | 95 | You can override all of this functionality inside `components/sidebar.js`. 96 | 97 | ### Changing source folder 98 | 99 | Add the relative location of your components and MDX files in `gatsby-config.js`. The default configuration is set to the `/src/components/` folder of your root project (which ideally should document every component): 100 | 101 | ```js 102 | { 103 | resolve: `gatsby-source-filesystem`, 104 | options: { 105 | name: `components`, 106 | path: `../src/components/`, 107 | }, 108 | }, 109 | ``` 110 | 111 | Gatsby will load all the JS and MDX files inside this folder. Then using the "transformer" plugins, Gatsby creates GraphQL endpoints for both components and MDX (`allMdx` and `allComponentMetadata`). 112 | 113 | > You can add as many file sources as you need. The transformer plugins will automatically group content based on their format (JS, MDX, etc), and it uses **all** the content that's loaded. 114 | 115 | ### Adding to existing projects 116 | 117 | This project is designed to be embedded inside existing projects. 118 | 119 | 1. `git clone` this repo into your project as a `docs` subfolder. 120 | 2. Optionally change the folder where components are loaded from _(see "Changing source folder")_ 121 | 3. `npm install && npm run develop` 122 | 123 | ### Creating pages from react-docgen 124 | 125 | This template is setup to generate pages based off MDX files in your project. This allows you to create a `Button.mdx` to document your ` 18 | 19 | 20 | ) 21 | 22 | export default AboutPage 23 | -------------------------------------------------------------------------------- /src/pages/index.js: -------------------------------------------------------------------------------- 1 | import React from 'react' 2 | import { Link } from 'gatsby' 3 | 4 | import Layout from '../components/layout' 5 | 6 | const IndexPage = ({ data }) => ( 7 | 8 |
9 |

Style Guide Guide

10 |

A boilerplate for creating superb style guides

11 |

12 | The homepage of a style guide should provide high-level information 13 | around what the design system is, what benefits it provides, who it’s 14 | for, and how to get started with it. Like any good index page, it should 15 | provide clear navigation to key parts of the website. 16 |

17 | 18 | Get Started 19 | 20 |

Design System Benefits

21 |

22 | Explain how the design system benefits users and the business. For 23 | inspiration, check out over 180 examples of design systems at 24 | Styleguides.io. tivizes teams to use the system, and shows components in 25 | the wild. 26 |

27 |

Contributing info

28 |

29 | If it’s desirable to have people from across the organization contribute 30 | to the design system, linking to the contributing page from the homepage 31 | could be a good idea. 32 |

33 |
34 | 35 | ) 36 | 37 | export default IndexPage 38 | -------------------------------------------------------------------------------- /src/pages/page-2.js: -------------------------------------------------------------------------------- 1 | import React from 'react' 2 | import { Link } from 'gatsby' 3 | 4 | import Layout from '../components/layout' 5 | 6 | const SecondPage = () => ( 7 | 8 |

Hi from the second page

9 |

Welcome to page 2

10 | Go back to the homepage 11 | 12 | ) 13 | 14 | export default SecondPage 15 | -------------------------------------------------------------------------------- /src/templates/page-default.js: -------------------------------------------------------------------------------- 1 | import React from 'react' 2 | 3 | export default ({ children }) => ( 4 |
5 |

Page

6 |
{children}
7 |
8 | ) 9 | -------------------------------------------------------------------------------- /src/templates/posts.js: -------------------------------------------------------------------------------- 1 | import React, { Component } from 'react' 2 | import { graphql } from 'gatsby' 3 | import MDXRenderer from 'gatsby-mdx/mdx-renderer' 4 | import { MDXProvider } from '@mdx-js/tag' 5 | 6 | import Layout from '../components/layout' 7 | import PropsTable from '../components/propstable' 8 | 9 | export default class MDXRuntimeTest extends Component { 10 | render() { 11 | const { children, data, tableOfContents } = this.props 12 | return ( 13 | 14 | 15 |
16 | {children} 17 |

{data.componentMetadata.displayName}

18 |

{data.componentMetadata.docblock}

19 | 20 | {data.mdx.code.body} 21 | 22 |

Props:

23 | 26 |
27 | 28 | 29 | ) 30 | } 31 | } 32 | 33 | export const pageQuery = graphql` 34 | query($id: String!, $name: String!) { 35 | mdx(id: { eq: $id }) { 36 | id 37 | code { 38 | body 39 | } 40 | tableOfContents 41 | } 42 | componentMetadata(displayName: { eq: $name }) { 43 | id 44 | displayName 45 | docblock 46 | doclets 47 | childrenComponentProp { 48 | name 49 | docblock 50 | required 51 | parentType { 52 | name 53 | } 54 | type { 55 | value 56 | } 57 | defaultValue { 58 | value 59 | computed 60 | } 61 | } 62 | composes 63 | } 64 | } 65 | ` 66 | -------------------------------------------------------------------------------- /src/tools/capitalize.js: -------------------------------------------------------------------------------- 1 | export default function toUpper(str) { 2 | return str 3 | .toLowerCase() 4 | .split(' ') 5 | .map(word => { 6 | console.log(`First capital letter: ${word[0]}`) 7 | console.log(`remain letters: ${word.substr(1)}`) 8 | return word[0].toUpperCase() + word.substr(1) 9 | }) 10 | .join(' ') 11 | } 12 | -------------------------------------------------------------------------------- /thumbnail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/whoisryosuke/gatsby-documentation-starter/a95cccf6b8ce7da98a850d6900537a6a7099dc40/thumbnail.png -------------------------------------------------------------------------------- /thumbnail2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/whoisryosuke/gatsby-documentation-starter/a95cccf6b8ce7da98a850d6900537a6a7099dc40/thumbnail2.jpg --------------------------------------------------------------------------------