Skip to content

Chicago Docs

Quick Start

Overview

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

This guide gets you set up quickly if you're already familiar with Gatsby. It assumes you have Gatsby installed. If you're not familiar with Gatsby, see their Quick Start or Tutorial.

Installation

Start a new site

To install the starter and create a new site, run:

Install the starter

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:

Install the core starter

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:

Install the theme

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

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

Install the core theme

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. It also adds a logo and favicon.

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

site/gatsby-config.js

JavaScript
module.exports = {
  siteMetadata: {
    title: 'The Full Title of Your Project',
    description: 'A brief description of your project and/or the site',
    siteUrl: 'https://www.your-site.com',
    siteLogo: 'logo.png', // adds the logo to the site
    siteLanguage: 'en',
    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
      },
    },
  ],
}

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.

site/gatsby-config.js

JavaScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
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',
              },
            ],
          },
        ],
      },  
    },
  ],
}

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.

This example shows the theme options and their default values.

site/gatsby-config.js

JavaScript
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 page (nested according to 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. You can customize an individual doc using the corresponding frontmatter field, such as showTOC.

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

src/docs/example-doc.mdx

MDX
---
title: Title for your doc
shortTitle: Alternate (shorter) title used in navigation
description: Brief description of the doc (used in metadata and search index)
showBreadcrumb: true
showPostNav: false
showSidebar: true
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.

Creating Pages

Any 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.

Note that the TOC and PostList components will work only with Doc pages. The TOC component relies on a Doc to have a table of contents, while the PostList component depends on the sidebar menus you've defined.

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

src/mdxPages/example-doc.mdx

MDX
---
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.
<Alert variant="success">
This is a great success.
</Alert>
©2020 K. A. BartoloGatsby theme: Chicago Docs