Gatsby Theme Chicago Docs (Core)

For full documentation and a demonstration of @kabartolo/gatsby-theme-chicago-docs, see the Chicago Docs Demo.

This guide is for the core version of this theme.

The Chicago Docs theme for Gatsby is a modern, professional docs site designed for open source projects.

Table of Contents

• Installation
• Quick Config
• Menus
• Theme Options
• Creating Docs
• Creating Pages

Installation

Start a new site

To install the core starter to start a docs site from scratch:

gatsby new your-site-name https://github.com/kabartolo/gatsby-starter-chicago-docs-core

Add to an existing site

To install the core theme so you can style your docs from scratch, run:

npm install @kabartolo/gatsby-theme-chicago-docs-core

Quick Config

Customize your site details in the gatsby-config.js file for your site. This creates the site metadata and configures the manifest file using gatsby-plugin-manifest. It also adds a favicon.

See Configuration for a more in-depth guide on configuring your site (note that githubUrl and siteLogo in the main theme are not used by the core theme).

Metadata

This table gives the name of each metadata field, its type, whether it is optional or required, the default value, and a description.

Name	Type	Info	Default	Description
title	string	optional	'' (empty string)	Used to set the meta title tag for your site. Also appears in the browser tab.
description	string	optional	'' (empty string)	Used to set the meta description tag for your site.
siteLanguage	string	optional	'' (empty string)	Used to set the meta language tag for your site.
siteUrl	string	optional	'' (empty string)	Used to set the canonical URL for your site.

Example

module.exports = {
  siteMetadata: {
    title: 'The Full Title of Your Project',
    description: 'A brief description of your project and/or the site',
    siteLanguage: 'en',
    siteUrl: 'https://www.your-site.com',
  },
  plugins: [
    '@kabartolo/gatsby-theme-chicago-docs-core',
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        name: 'The Full Title of Your Project',
        short_name: 'Shorter Title',
        start_url: '/',
        background_color: '#fff',
        theme_color: '#eee',
        display: 'standalone',
        icon: 'src/assets/favicon.ico', // creates a favicon
      },
    },
  ],
}

Menus

The main menu and the sidebar menus are defined in your site's gatsby-config.js file. For more information on creating these menus, see Configuration: Menus.

This example shows how the main menu and sidebar menus are defined for the demo site. Note that if you omit the items list, all posts from the directory will be added automatically.

module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs-core',
      options: {
         mainMenu: [
          {
            name: 'Documentation',
            path: '/docs/',
          },
          {
            name: 'Tutorials',
            path: '/tutorials/',
          },
        ],
        sidebarMenus: [
          {
            name: 'Documentation',
            slug: 'docs',
            items: [
              {
                slug: 'quick-start',
              },
              {
                name: 'Configuration',
                slug: 'configuration',
                isGroup: true,
                items: [
                  {
                    slug: 'site-options'
                  },
                  {
                    slug: 'menus',
                  },
                  {
                    slug: 'search-config',
                  },
                ],
              },
              // code omitted for brevity            
            ],
          },
          {
            name: 'Tutorials',
            slug: 'tutorials',
            items: [
              {
                slug: 'tutorial1',
              },
            ],
          },
        ],
      },  
    },
  ],
}

Theme Options

Several options are available to customize your site's directory structure and how the site behaves. See Configuration: Theme Options for more details. Note that @kabartolo/gatsby-theme-chicago-docs defines more options than the core theme. The core theme uses the options listed below.

Options

This table gives the name of each theme option, its type, whether it is optional or required, the default value, and a description. These options (except sidebarMenus) can be fetched using the useThemeOptions hook.

Name	Type	Info	Default	Description
assetsPath	string	optional	src/assets	Directory for all assets used in your site.
basePath	string	optional	'' (empty string)	Base path of your docs site, such as /docs.
basePathLabel	string	optional	'Home'	Label for base path in breadcrumb links.
docsPath	string	optional	src/docs	Directory for all MDX docs for your site (i.e., MDX files that should use the Doc page component).
pagesPath	string	optional	'src/mdxPages'	Directory for your site's pages (i.e., MDX files that should use the Page page component).
mainMenu	array of objects	optional	[]	List of main menu items (see Configuration: Main Menu).
sidebarMenus	array of objects	optional	[]	List of sidebar menus (the sidebar menu associated with a doc is stored in the doc's pageContext prop; also see Configuration: Sidebar Menu).
allowDocsSearch	boolean	optional	true	Whether a search index is fully populated with MDX files from the docsPath folder. Set to false to use a different search strategy.
alwaysShowBreadcrumb	boolean	optional	true	Used as default value for the showBreadcrumb frontmatter field for an individual doc.
alwaysShowPostNav	boolean	optional	true	Used as default value for the showPostNav frontmatter field for an individual doc.
alwaysShowSidebar	boolean	optional	true	Used as default value for the showSidebar frontmatter field for an individual doc.
alwaysShowTOC	boolean	optional	true	Used as default value for the showTOC frontmatter field for an individual doc.
skipMDXConfig	boolean	optional	false	Whether to skip gatsby-plugin-mdx configuration for the theme.

Example

This example shows the theme options (except menus) and their default values:

module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs',
      options: {
        assetsPath: 'src/assets',
        basePath: '/',
        basePathLabel: 'Home',
        docsPath: 'src/docs',
        pagesPath: 'src/mdxPages',
        allowDocsSearch: true,
        alwaysShowBreadcrumb: true,
        alwaysShowPostNav: true,
        alwaysShowSidebar: true,
        alwaysShowTOC: true,
        skipMDXConfig: false,
      }
    }
  ]
}

Creating Docs

Docs are MDX files that are displayed using the Doc page component. The sidebar menu helps define each doc's breadcrumb links and post navigation (links to previous and next docs). These are stored along with the sidebar menu in the doc's pageContext prop, which you can access from the Doc page component:

// src/components/Doc/index.js

import React from 'react';
import PropTypes from 'prop-types';

export default function Doc({ data, pageContext }) {
  return (
    <div>
      <pre>{JSON.stringify(data, null, 2)}</pre>
      <pre>{JSON.stringify(pageContext, null, 2)}</pre>
    </div>
  );
}

Doc.propTypes = {
  data: PropTypes.instanceOf(Object).isRequired,
  pageContext: PropTypes.instanceOf(Object).isRequired,
};

Frontmatter fields

This table gives the name of each frontmatter field, its type, whether it is optional or required, the default value, and a description.

See Configuration: Frontmatter for more details on the available frontmatter fields.

Name	Type	Info	Default	Description
title	string	optional	value of shortTitle or 'Untitled'	Title of the doc. Used in the meta title tag and appears in the browser tab.
shortTitle	string	optional	'' (empty string)	Shorter title used in place of the title field in doc navigation (e.g., in the sidebar).
description	string	optional	'' (empty string)	Description of the doc. Used in the search index and in the meta description tag for the page.
showBreadcrumb	boolean	optional	value of alwaysShowBreadcrumb	Can be used to determine whether the breadcrumb links should appear at the top of this doc.
showPostNav	boolean	optional	value of alwaysShowPostNav	Can be used to determine whether links to the previous and next docs should appear at the bottom of this doc.
showSidebar	boolean	optional	value of alwaysShowSidebar	Can be used to determine whether the sidebar should appear for this doc.
showTOC	boolean	optional	value of alwaysShowTOC	Can be used to determine whether the standalone table of contents (the TOC component) should appear for this doc.

Example

To create a doc, create an MDX file in src/docs (or the docsPath defined in the theme options):

---
title: Title for your doc
shortTitle: Alternate (shorter) title used in navigation
description: Brief description of the doc (used in metadata and search index)
showPostNav: false
showTOC: false
---

## The first header should be an h2

This post will not show previous/next navigation or a table of contents since
`showPostNav` and `showTOC` are set to `false`.

See Configuration: Frontmatter for details on the available frontmatter fields. See Guide to MDX for help writing MDX and Markdown.

Creating Pages

Other pages can be created using React, regular JavaScript, or MDX. An MDX file in src/mdxPages (or the pagesPath theme option) will be rendered using the Page component, which does not include layout features such as a sidebar menu or breadcrumb links.

To create a non-doc MDX page, create an MDX file in your specified pagesPath directory:

---
title: Title for your page
description: Brief description of the page (used in metadata)
---

## The first header should be an h2