Gatsby Theme Chicago Docs

For full documentation and a demonstration of this theme, see the Chicago Docs Demo.

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 starter and create a new site, run:

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

If you just want the data without the components or styling, use 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 just the theme to an existing site, run:

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

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

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

Quick Config

The default configuration of @kabartolo/gatsby-starter-chicago-docs creates a site that looks and behaves like the demo. You'll just need to 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 logo and favicon.

See Configuration for a more in-depth guide on configuring your site.

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 and next to the logo in the header. | | 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. | | siteLogo | string | optional | '' (empty string) | Filename for your logo, which should live in src/assets (or the assetsPath theme option). This creates a logo that appears to the left of the site title with a fixed height of 30px. To customize the logo further, shadow the Logo component in @kabartolo/gatsby-theme-chicago-docs/src/components/Layout/Header/logo.js. | | siteUrl | string | optional | '' (empty string) | Used to set the canonical URL for your site. | | githubUrl | string | optional | '' (empty string) | Used to create a GitHub icon in the header that opens your GitHub project in a new tab. |

Example

module.exports = {
  siteMetadata: {
    title: 'The Full Title of Your Project',
    description: 'A brief description of your project and/or the site',
    siteLanguage: 'en',
    siteLogo: 'logo.png', // adds the logo to the site
    siteUrl: 'https://www.your-site.com',
    githubUrl: `https://www.github.com/repository/project-name/`,
  },
  plugins: [
    '@kabartolo/gatsby-theme-chicago-docs',
    {
      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:

module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs',
      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',
              },
            ],
          },
        ],
      },  
    },
  ],
}

If you specify isGroup: true for a list item, the item will appear as an accordion of posts from src/docs/{slug} (see theme options to change where your docs live).

If you omit the items list, all posts from the directory will be added automatically.

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.

Options

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

| 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 menu items that will appear in the header (see Configuration: Main Menu). | | sidebarMenus | array of objects | optional | [] | List of menus that will appear in the sidebar of your site (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 | Whether breadcrumb links are always displayed at the top of each doc. Can be overridden by the showBreadcrumb frontmatter field for an individual doc.| | alwaysShowPostNav | boolean | optional | true | Whether to always show links to the previous and next docs at the bottom of a doc page. Can be overridden by the showPostNav frontmatter field for an individual doc. | | alwaysShowSidebar | boolean | optional | true | Whether to always show the sidebar for docs. Can be overridden by the showSidebar frontmatter field for an individual doc. | | alwaysShowTOC | boolean | optional | true | Whether to always show the table of contents (TOC component) for each doc. Can be overridden by the showTOC frontmatter field for an individual doc. | | primaryResultsOnly | boolean | optional | false | When searching, whether to show only only matches in the title, description, and/or header. If set to false, will also show paragraph matches. | | sidebarAllowMultipleOpen | boolean | optional | true | Whether multiple accordion menus in the sidebar can be open at the same time. | | sidebarAllowTOC | boolean | optional | true | Whether to show a dropdown table of contents for each doc in the sidebar. | | sidebarDepth | number | optional | 3 | Total depth of nested accordions to display in the sidebar (including table of contents). | | skipMDXConfig | boolean | optional | false | Whether to skip gatsby-plugin-mdx configuration for the theme. | | toggleTheme | boolean | optional | true | Whether a theme toggle button should be shown in the header. |

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',
        sidebarDepth: 3,
        allowDocsSearch: true,
        alwaysShowBreadcrumb: true,
        alwaysShowPostNav: true,
        alwaysShowSidebar: true,
        alwaysShowTOC: true,
        primaryResultsOnly: false,
        sidebarAllowMultipleOpen: true,
        sidebarAllowTOC: true,
        skipMDXConfig: false,
        toggleTheme: true,
      }
    }
  ]
}

Creating Docs

Docs are MDX files that are displayed using the Doc page component. Docs can be navigated in the sidebar. A doc includes breadcrumb links at the top of the doc page; these are based on the nesting of the post in the sidebar menu defined by you. The links to the previous and next docs at the bottom of the doc page are also determined by this sidebar menu.

A table of contents (using the TOC component) also appears for each doc.

You can customize how all docs appear using the appropriate theme option, such as alwaysShowTOC (this option determines whether all docs show a table of contents). You can customize an individual doc using the corresponding frontmatter field, such as showTOC.

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 at the top of the doc and 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 | Whether the breadcrumb links appear at the top of this doc. | | showPostNav | boolean | optional | value of alwaysShowPostNav | Whether links to the previous and next docs appear at the bottom of this doc. | | showSidebar | boolean | optional | value of alwaysShowSidebar | Whether the sidebar should appear for this doc. | | showTOC | boolean | optional | value of alwaysShowTOC | 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. This component provides all Chicago Docs components but does not include layout features such as a sidebar 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

Use Chicago Docs components here.

<TOC />