Configuration

• Site title and description
• Manifest
• Favicon
• Additional font weights
• Image compression
• Global search
• Edit on Github link
• Other options

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-512.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. You can also tweak the image quality based on design tolerance and performance thresholds.

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        withWebp: true, // true, false (default false)
        imageQuality: 50, // 0-100 (default 75)
      },
    },
  ],
};

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:

1. set the isSearchEnabled theme option to true

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

2. 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',
        },
      },
    },
  ],

Other options

• additionalFontWeights – add support for additional Plex font weights. Don’t forget to specify italics for the additional weights if needed.

• mdxExtensions – change the file extensions processed by gatsby-mdx (default [‘.mdx’, ‘.md’])

• titleType – pick between three formats for the <title> element for your site. Here are the three options using this page as an example:

  • page: “Configuration” (default)
  • site: “Gatsby Theme Carbon”
  • append: “Gatsby Theme Carbon – Configuration”

plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        additionalFontWeights: ['200', '200i'],
        mdxExtensions: ['.mdx'],
        titleType: 'append'
      },
    },
  ],