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