Create custom design system documentation sites powered by the design system supereditor, Supernova.io. This repository provides a fully coded, fully customizable, typescript-enabled Gatsby site you can just connect to Supernova, run and start customizing it (or serving to your team) to your liking!
This starter implements all functionality you might need for your design system docs:
- Full support for all Supernova content blocks, including custom blocks and ability to code your own blocks
- Rendering of design tokens, assets, components, rich text, images + all other necessary elements
- Responsive layout and 2 different ways how to structure your content
- Integration with Supernova editor configuration options
- Fully customizable landing page included with the starter
- Fully implemented client-side site search using Fuse.js
And of course, features that make all developers happy!
- Excellent, extendable code structure
- Componentized design
- Fully Typescript-enabled code
- Fully Typescript-enabled Supernova GraphQL binding
- Pre-defined set of useful GraphQL queries to get static data you need
- Interactive command-line setup
-
npm run devand all works out of the box
Right out of the box, your documentation site comes with a beautifully styled template and elements, which you can fully customize to your liking - or redo the site completely, should you want to.
First, create a design system within Supernova. You can also optionally write a little bit of content for your documentation, use elements from Figma, connect Storybook or whatever you fancy. Here is our official starting guide that you can follow.
$ git clone https://github.com/Supernova-Studio/gatsby-documentation-site.git
$ npm install
You can optionally use the Gatsby CLI to achieve the same thing.
$ gatsby new my-design-system-docs https://github.com/Supernova-Studio/gatsby-documentation-site
This project uses on Gatsby version 4 so you can enjoy advanced new features like SSR, DSG, parallel querying and many more. However, this also means that you will need Node 14.15+ at minimum to run it. If you are still on previous versions, you can use NVM to install the new one and freely switch between them.
If you are running Node 17 and above, you will likely encounter error when running any of npm run commands. The reason is explained here and is known "issue" for this version of Gatsby. From our testing, the best way to solve this issue is to replace commands in package.json with the following modification:
"scripts": {
"dev": "export NODE_OPTIONS=--openssl-legacy-provider; gatsby develop",
"build": "export NODE_OPTIONS=--openssl-legacy-provider; gatsby build",
},
Your site needs to know to what design system to use. This starter provides a simple way of configuring all neccessary information by running the following command:
npm run setup
This interactive setup will ask for an API key first. Click on your Supernova profile picture > Profile settings > Authentication and generate one. Then, select workspace / design system / version you want to use from the interactive shell. Once completed, it will write the following files from which the site draws the configuration:
.env.development
.env.production
We have added .gitignore to ignore those generated files - you should never commit them as they contain your API key!
Once all is set, here are the commands you can use for various purposes
Runs development version of the site with hot-reload enabled. The site can be found at:
http://localhost:8000/
Additionally, this spins up a GraphQL browser allowing you to browse your data which you can access at:
http://localhost:8000/___graphql
Creates production build that you put on any static hosting service (AWS S3 Bucket, Azure, GCP..)
Runs production server locally with your site hosted on it. Run npm run build before you run the serve.
As this is still beta, we are working hard on improving it before the first official release. The following are areas we'd like to solve before general release:
- Better CSS structure, and cleaner styling, likely using SCSS or some other preprocessor
- SEO improvements like dynamic titles, header, descriptions, tw and fb tags and more
- Implementation of custom configurable properties from exporter packages
This starter package is powered by Supernova Gatsby source plugin, which you can use as a standalone package if you want to create your site completely from scratch.
However, we strongly recommend that you use this project as a base (and remove all that you don't need), as it solves many additional issues you will otherwise be forced to solve yourself, like figuring out how to query data properly, how to properly make Gatsby + Typescript work and many, many other - annoying - issues.
If you have additional ideas about how to make this project better, let us know by opening an issue! You can also open pull requests if you've worked on improving something yourself and would like to contribute back to the community.
We will be reviewing feature-pull-requests on case-by-case basis, but in general, we are super open to your new ideas and we welcome them! And finally, thank you for your support! You are an amazing community.
Supernova Engineering Team