This is the repo for https://qri.io, our beloved website. Changes, fixes & pull requests are welcomed & appreciated.
This site is built with gatsby, a javascript static site generator, using the gatsby-gitbook-starter site template. The template has been modified to serve both a full-featured documentation site (markdown files in /docs) and standard pages (jsx files in /pages)
You should have node and yarn already installed on your machine.
You'll also need gatsby-cli, which you can install with npm install -g gatsby-cli
To run the dev server:
- Clone this repository
- cd to the project directory
- Install dependencies
yarn - run the development server
gatsby develop - Open
http://localhost:8000in your web browser
Things such as the site title, navbar links, docs group ordering, etc are all config-driven from config.js.
Documentation pages can be added by creating markdown files in the /docs directory. Directories in /docs become groups, and each documentation article must belong to a group.
Ordering and Grouping of Docs are driven by docsSections in config.js. This array includes the full hierarchy used in the docs table of contents (left sidebar). Entries can either be a path to a markdown file (equivalent to that article's url) or an object with title, path, description, and items defining a group. The sidebar items will be displayed in whatever order the strings or objects appear in the array.
Groups need a path because we auto-generate an index page for groups, and they are clickable in the sidebar.
Gatsby will create a page for every markdown file it finds, but only articles included in docsSections will show up in the sidebar.
There is a frontmatter item weight which used to be used for ordering but is now deprecated
Redirects are defined in gatsby-node.js. The plugin gatsby-plugin-netlify generates pages for each redirect during build.
For the /docs section of the site, all content lives in /content/docs, and can be markdown or MDX. These are transformed into pages via createPages() in gatsby-node.js, which does all the fancy graphQL work to make the docs navigation (left sidebar) and contents (right sidebar).
Most of the content in /pages is JSX, but you can mix in markdown files as well. These are simply rendered and placed into a simple layout component (src/layouts/markdown-page.js). There is no complex graphQL stuff, but the following frontmatter fields should exist so we can populate the title and head meta on these pages:
---
metaTitle: "Frequently Asked Questions"
metaDescription: "Frequently Asked Questions about Qri"
---
If you move around existing pages (such as moving a page down into a directory) you may have issues rebuilding in development. You can safely delete the .cache directory, which will be rebuilt the next time you run gatsby develop
There are a few one-off scripts that programmatically generate content. They live in the /scripts directory. each one-off is a .sh script. Read the comments in each file for instructions on running, and what the script does.
To add a job listing, create a markdown file in src/pages/jobs with a filename that starts with jobs-. This will be picked up by the graphql query in src/pages/jobs/index and will show up in the list.
If no markdown files match the query, a message saying there are no current openings is shown instead.
You can archive a job posting by changing its filename to not start with jobs-, for example: archive-job-backend-software-engineer. Keeping these around will make it easier to turn them back on or adapt them for future positions.