README.md

NI Gatsby Themes

This repo contains Gatsby themes that we use to create the NI Design System website. 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.

Entirely built upon the fantastic gatsby-theme-apollo theme from Apollo.

Packages

• gatsby-theme-ni
• gatsby-theme-ni-docs

Publish theme changes

• npx lerna publish and follow the prompts
• cd packages/gatsby-theme-ni-docs/ or cd packages/gatsby-theme-ni/
• npm login
• npm publish

Basic usage

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

$ npm install gatsby gatsby-theme-ni

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-ni',
      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-ni';

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-ni. 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/