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

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',
},
__experimentalThemes: [
{
resolve: '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: [
{
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',
},
},
],
__experimentalThemes: [

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.
__experimentalThemes: [
{
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.

__experimentalThemes: [
{
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',
},
__experimentalThemes: [
{
resolve: 'gatsby-theme-carbon',
options: {
name: 'Gatsby Theme Carbon Starter',
shortName: 'Carbon Starter',
withWebp: true,
},
},
],
};

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
__experimentalThemes: [
{
resolve: 'gatsby-theme-carbon',
options: {
isSearchEnabled: true
},
},
],
  1. 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.

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.

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