README.md

Gatsby Theme Carbon

Get started using with the Gatsby Carbon theme which includes all configuration you might need to build a beautiful site inspired by the Carbon Design System.

🧗 Getting started

1. Create your site

Use the gatsby CLI to bootstrap your site with the starter

npx gatsby new my-carbon-site https://github.com/carbon-design-system/gatsby-starter-carbon-theme

2. Start developing

Navigate into your directory and start it up using one of the following snippets. You can tell which command to use based on the lock file at the root of your project (yarn.lock for yarn and package-lock.json for npm).

yarn

    cd my-carbon-site/
    yarn develop

npm

    cd my-carbon-site/
    npm run develop

3. Make some changes!

Navigate to localhost:8000 to see your site running

Each of the Items in your side bar correlates to a MDX file in your src/pages/ directory. Navigate to a site and try editing the corresponding markdown file. You'll be able to see it update live!

🔍 What's in here?

Lets check out the structure of our project

.
├── LICENSE
├── README.md
├── gatsby-config.js
├── node_modules
├── package.json
├── public
├── src
│   ├── gatsby-theme-carbon
│   └── pages
└── yarn.lock

1. /node_modules: This directory contains all of the modules of code that your project depends on (npm packages) are automatically installed.

2. /src: This directory will contain all of the code related to what you will see on the front-end of your site.

   • gatsby-theme-carbon this is where you'll override (known as shadowing) the default gatsby-theme-carbon components
   • pages This is where most of your content will live. You'll represent each page with an MDX file.

3. .gitignore: This file tells git which files it should not track / not maintain a version history for.

4. gatsby-config.js: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description. You'll notice that all of the configuration for the site is coming from gatsby-theme-carbon

5. LICENSE: Gatsby is licensed under the Apache 2.0 license.

6. yarn.lock (See package.json below, first). This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. (You won’t change this file directly).

7. package.json: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.

8. README.md: This file!

👷‍ Components

This is where we'll document the various utility components as they're added.

📘 Resources

1. Gatsby tutorial
2. MDX

👻 Configuration and Shadowing

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

Favicon and 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',
        icon: './src/images/custom-favicon.png', // defaults to IBM rebus eye
      },
    },
  ],
  __experimentalThemes: [

Global Styles

You can inject global styles into the theme's style bundle by shadowing gatsby-theme-carbon/styles/_global.scss in your project's src directory. This technique is especially useful for node_module dependencies that assume a single bundle (such as individual carbon-components).

For your application's local styles, you can just import your style sheet directly into a gatsby-browser.js file at the root of your project.

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

404 implementation

1. Make a 404.js in your src/pages
2. Import the 404 component from the theme
3. Export the component and provide your own links
4. If necessary, configure your server to route unknown routes to 404.html

import React from 'react';
import { FourOhFour } from 'gatsby-theme-carbon';

const links = [
  { href: '/components/markdown', text: 'Markdown' },
  { href: '/components/Aside', text: 'Aside' },
  { href: '/components/demo', text: 'Demo' },
];

const Custom404 = () => <FourOhFour links={links} />;

export default Custom404;

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,
      },
    },
  ],
};

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

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

🚀 Deployment

Coming soon!