Configuration

Gatsby themes allow you to override configuration from the theme by defining the same property in your gatsby-config.js at the root of your project. You can see the default configuration provided by the theme’s gatsby-config.js file.

Site Title and Description
Manifest
Favicon
Additional font weights
Image Compression
Global Search
Edit on Github link

Site Title and Description

To add a title and description to each page, simply provide them to siteMetadata in your gatsby-config.js file.

module.exports = {
  siteMetadata: {
    title: 'Gatsby Theme Carbon',
    description: 'A Gatsby theme for the carbon design system',
    keywords: 'gatsby,theme,carbon',
  },
  plugins: ['gatsby-theme-carbon'],
};

Manifest

One of the first configurations should be to override the default manifest options, you can do this in gatsby-config.js. Any options you don’t set, will be provided by the theme. See the example project.

siteMetadata: {
    title: 'Gatsby Theme Carbon',
  },
  plugins: [
    'gatsby-theme-carbon',
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        name: 'Carbon Design Gatsby Theme',
        short_name: 'Gatsby Theme Carbon',
        start_url: '/',
        background_color: '#ffffff',
        theme_color: '#0062ff',
        display: 'browser',
      },
    },
  ],

Favicon

If you need to override the default favicon, you can do so by passing a relative path to the icon. It’s recommended to provide a 512 x 512 version.

IMPORTANT: For best results, if you’re providing an icon for generation it should be…

at least as big as the largest icon being generated (512x512 by default).
square (if it’s not, transparent bars will add to make it square).
of one of the follow formats: JPEG, PNG, WebP, TIFF, GIF or SVG.

plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        iconPath: './src/images/custom-icon.png'
      },
    },
  ],

Additional font weights

If needed, you can add support for additional Plex font weights. Don’t forget to specify italics for the additional weights if needed.

plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        // will get added to default [300, 400, 600]
        additionalFontWeights: ['200', '200i]
      },
    },
  ],

Image Compression

You can enable WebP by passing withWebp: true or providing your own optimization level. See the gatsby-remark-images plugin options.

module.exports = {
  siteMetadata: {
    title: 'Gatsby Theme Carbon',
  },
  plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        name: 'Gatsby Theme Carbon Starter',
        shortName: 'Carbon Starter',
        withWebp: true,
      },
    },
  ],
};

Global Search

The GlobalSearch component is disabled by default. If you’d like to implement search functionality, you’ll need to follow these two steps:

set the isSearchEnabled theme option to true

  plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        isSearchEnabled: true
      },
    },
  ],

Shadow the example search implementation at /src/util/hooks/useSearch.js

import { useEffect } from 'react';
const useAlgoliaSearch = () => {
  // ...
};
export default useAlgoliaSearch;

The example useSearch hook demonstrates implementing search with Algolia. Algolia is free for open source libraries. You can shadow this hook and replace it with your Algolia credentials or a library of your choosing.

Edit on GitHub link

To add a link to the bottom of each page that points to the current page source in GitHub, provide an repository object to siteMetadata in your gatsby-config.js file. You can provide a baseUrl, and if needed, the subDirectory where your site source lives.

  plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        repository: {
          baseUrl: 'https://github.com/carbon-design-system/gatsby-theme-carbon',
          subDirectory: '/packages/example',
        },
      },
    },
  ],

Edit this page on GitHub

Contributions

Guides: Shadowing