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',
  },
  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

Site-wide search is provided by the theme. The only requirement for a page to show up in the results is for it to have title set in the frontmatter. To render more helpful search results (and improve SEO), you’ll want to make sure your pages have description set in the frontmatter as well.

Global search is enabled by default. To disable it, set the isSearchEnabled option to false.

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

Under the hood, we use Lunr to create our search index. If necessary, you tweak the search scoring algorithm and source nodes. To do so, provide your own resolvers object to the lunrOptions theme option.

Edit on GitHub link

To add a link to the bottom of each page that points to the current page source in GitHub, provide a repository object to siteMetadata in your gatsby-config.js file. You can provide a baseUrl, and if needed, the subDirectory and branch 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',
          branch: 'master',
        },
      },
    },
  ],

Medium

Automatically grab posts from Medium’s RSS feed and populate ArticleCards. Enable gatsby-source-medium-feed by shadowing this plugin and providing a userName. For guidance on how to use this plugin checkout MediumPosts.

plugins: [
  {
    resolve: 'gatsby-source-medium-feed',
    options: {
      userName: '@...', // Medium user name or publication
      name: 'MediumFeed', // GraphQL query AllMediumFeed
    },
  },
];

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 four formats for the <title> element for your site. Here are the four options using this page as an example:

    • page: “Configuration” (default)
    • site: “Gatsby Theme Carbon”
    • append: “Gatsby Theme Carbon – Configuration”
    • prepend: “Configuration - Gatsby Theme Carbon”
plugins: [
    {
      resolve: 'gatsby-theme-carbon',
      options: {
        additionalFontWeights: ['200', '200i'],
        mdxExtensions: ['.mdx'],
        titleType: 'append'
      },
    },
  ],
Edit this page on GitHub
Previous
Contributions
Next
Guides: Shadowing