Skip to content
πŸ’œ Themes that we use to build Gatsby sites at Apollo
JavaScript CSS
Branch: master
Clone or download
trevorblades Publish
 - gatsby-theme-apollo-docs@1.3.2
Latest commit 5143f66 Aug 16, 2019

README.md

Apollo Gatsby Themes

This repo contains Gatsby themes that we use to create websites at Apollo. In its most basic implementation, the theme provides a CSS reset, styles for regular HTML elements (h1, h2, p, li, etc.), and a handful of useful layout components.

Packages

Basic usage

First, install gatsby and the theme that you want to use. This example will be using the base theme, gatsby-theme-apollo.

$ npm install gatsby gatsby-theme-apollo

Using a Gatsby theme is really easy! Simply configure your theme under the __experimentalThemes property in your Gatsby config. The only required option here is root, which should always be __dirname. It's also a good idea to give your site a title and description, as defined under the siteMetadata property in the config.

// gatsby-config.js
module.exports = {
  __experimentalThemes: [
    {
      resolve: 'gatsby-theme-apollo',
      options: {
        root: __dirname
      }
    }
  ],
  siteMetadata: {
    title: 'My great website',
    description: 'A simple Gatsby theme example'
  }
};

Now add some React components to your src/pages directory, and you're off to the races! More info about creating pages in Gatsby here. Here's an example page:

// src/pages/index.js
import React from 'react';
import {Layout, LogoTitle} from 'gatsby-theme-apollo';

export default function Home() {
  return (
    <Layout>
      <LogoTitle />
      I love themes!
    </Layout>
  );
}

As you can see, the page is wrapped in a Layout component and contains a LogoTitle, both coming from gatsby-theme-apollo. Our base theme has a bunch of useful shared components like these, and they're all documented in the base theme.

Deploying to a subdirectory

In order to deploy a Gatsby site to a subdirectory, there are a few extra steps to take. First, you must provide a pathPrefix property in your Gatsby config. This option combined with the --prefix-paths option in the Gatsby CLI will handle most of the hard work. Read more about path prefixing in Gatsby here.

// gatsby-config.js
module.exports = {
  ...
  pathPrefix: '/YOUR_PATH_PREFIX'
};

Now, when you run npx gatsby bulid --prefix-paths, all pages, references to static assets, and links between pages will be prefixed with your custom path. That means that if you made a page with the path /about, it will live at /YOUR_PATH_PREFIX/about. In order for this to work within our server configuration, your website files also must exist in a directory with the same name. Here's how this sequence of events would look if you ran commands in your terminal:

$ npx gatsby build --prefix-paths
$ mkdir -p YOUR_PATH_PREFIX
$ mv public/* YOUR_PATH_PREFIX
$ mv YOUR_PATH_PREFIX public/

We use Netlify to deploy our websites, so to express this slightly more complicated build process to them, create a netlify.toml file that follows this pattern:

# netlify.toml
[build]
  base = "/"
  publish = "public/"
  command = "gatsby build --prefix-paths && mkdir -p YOUR_PATH_PREFIX && mv public/* YOUR_PATH_PREFIX && mv YOUR_PATH_PREFIX public/"

We use Fly to manage our server rewrites and redirects. To point your new Netlify deployment to a page on apollographql.com, first create a new backend using your site's Netlify alias. Next, you'll need to add two rewrite rules:

  • /YOUR_PATH_PREFIX/:page ➑️ /YOUR_PATH_PREFIX/$page
  • /YOUR_PATH_PREFIX ➑️ /YOUR_PATH_PREFIX

Be sure to set the priority of each of these rules to 3, or a value lower than the top two redirect rules that apply to our website root. Once these rewrite rules take effect, your site will be live at https://apollographql.com/YOUR_PATH_PREFIX.

You can’t perform that action at this time.