Skip to content

Chicago Docs

Site options

Overview

This section describes the options that help customize your site.

The default options will create a site with all the features shown in this demo. You can turn off features such as the searchbar if you prefer. You can also turn off the table of contents and other features for individual posts.

Folder Structure

The src folder for your site contains your docs, pages, and assets (such as images).

All documentation files should be placed in the docsPath directory (default src/docs) defined in the theme options. These files will be displayed using the Doc template in @kabartolo/gatsby-theme-chicago-docs, with sidebar navigation, breadcrumb links, and previous/next navigation, as well as a table of contents. These features can be turned off for individual posts.

You can further organize your docs within the src/docs folder, such as src/docs/api and src/docs/tutorials. These nested folders can form groups of docs in the sidebar menu, or you can create separate sidebar menus for each nested folder.

Place assets such as images and your site logo in src/assets, or the assetsPath defined in the theme options.

The src/mdxPages directory, or the pagesPath defined in the theme options, contains the non-docs MDX pages on your site. Any MDX files in this folder will use the Page template, which has access to most Chicago Docs components (PostList and TOC will work only with Doc posts).

Example directory structure

site
└── src
    ├── assets
    │   ├── chicago-docs-logo.png
    ├── docs
    │   ├── api
    │   │   ├── index.mdx
    │   │   └── methods.mdx
    │   └── tutorials
    │       ├── index.mdx
    │       └── tutorial1.mdx
    ├── mdxPages
        └── index.mdx
    └── pages
        └── 404.js

Site Metadata

Set your site's metadata in the gatsby-config.js file for your site. Some of these fields are used in the SEO component, which uses React Helmet to create your site's meta tags.

Metadata fields

  • title

    optional    string
    default: '' (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

    optional    string
    default: '' (empty string)

    Used to set the meta description tag for your site.

  • siteLanguage

    optional    string
    default: '' (empty string)

    Used to set the meta language tag for your site.

  • siteLogo

    optional    string
    default: '' (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

    optional    string
    default: '' (empty string)

    Used to set the canonical URL for your site.

  • githubUrl

    optional    string
    default: '' (empty string)

    Used to create a GitHub icon in the header that opens your GitHub project in a new tab.

site/gatsby-config.js

JavaScript
module.exports = {
  siteMetadata: {
    title: 'Your Site Title',
    description: 'Brief description of your site and project',
    siteLanguage: 'en',
    siteLogo: 'logo.png',
    siteUrl: 'localhost:8000',
    githubUrl: `https://www.github.com/repository/your-project`,
  },
};

The Chicago Docs Gatsby Starter also comes with gatsby-plugin-manifest. This plugin is also used to create your site's favicon. This plugin must also be configured in your gatsby-config.js file:

site/gatsby-config.js

JavaScript
module.exports = {
  //...
  {
    resolve: 'gatsby-plugin-manifest',
    options: {
      name: 'Your Site Title',
      short_name: 'Shorter Title',
      start_url: '/',
      background_color: '#fff',
      theme_color: '#eee',
      display: 'standalone',
      icon: 'src/assets/favicon.ico', // creates a favicon
    },
  },
};

Theme Options

Several theme options help you customize how your site behaves.

Theme options

  • assetsPath

    optional    string
    default: 'src/assets'

    Directory for all assets used in your site.

  • basePath

    optional    string
    default: '' (empty string)

    Base path of your docs site, such as /docs.

  • basePathLabel

    optional    string
    default: 'Home'

    Label for base path in breadcrumb links.

  • docsPath

    optional    string
    default: 'src/docs'

    Directory for all MDX docs for your site (i.e., MDX files that should use the Doc page component).

  • pagesPath

    optional    string
    default: 'src/mdxPages'

    Directory for your site's pages (i.e., MDX files that should use the Page page component).

  • mainMenu

    optional    object[]
    default: []

    List of menu items that will appear in the header (see Configuration: Main Menu).

  • sidebarMenus

    optional    object[]
    default: []

    List of menus that will appear in the sidebar of your site (see Configuration: Sidebar Menu).

  • allowDocsSearch

    optional    boolean
    default: 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

    optional    boolean
    default: 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

    optional    boolean
    default: 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

    optional    boolean
    default: true

    Whether to always show the sidebar for docs. Can be overridden by the showSidebar frontmatter field for an individual doc.

  • alwaysShowTOC

    optional    boolean
    default: 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

    optional    boolean
    default: 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

    optional    boolean
    default: true

    Whether multiple accordion menus in the sidebar can be open at the same time.

  • sidebarAllowTOC

    optional    boolean
    default: true

    Whether to show a dropdown table of contents for each doc in the sidebar.

  • sidebarDepth

    optional    number
    default: 3

    Total depth of nested accordions to display in the sidebar (including table of contents).

  • skipMDXConfig

    optional    boolean
    default: false

    Whether to skip gatsby-plugin-mdx configuration for the theme.

  • toggleTheme

    optional    boolean
    default: true

    Whether a theme toggle button should be shown in the header.

site/gatsby-config.js

JavaScript
module.exports = {
  plugins: [
    {
      resolve: '@kabartolo/gatsby-theme-chicago-docs',
      options: {
        docsPath: `{__dirname}/content/docs`,
        allowDocsSearch: false,
        alwaysShowTOC: false,
        sidebarAllowMultipleOpen: false,
        toggleTheme: false,
      }
    }
  ]
}

Frontmatter

The frontmatter fields for a Chicago Docs doc post include title and description values and boolean values that determine whether to display the table of contents or another feature for an individual post.

Frontmatter fields

  • title

    optional    string
    default: 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

    optional    string
    default: '' (empty string)

    Shorter title used in place of the title field in doc navigation (e.g., in the sidebar).

  • description

    optional    string
    default: '' (empty string)

    Description of the doc. Used in the search index and in the meta description tag for the page.

  • showBreadcrumb

    optional    boolean
    default: value of alwaysShowBreadcrumb

    Whether the breadcrumb links appear at the top of this doc.

  • showPostNav

    optional    boolean
    default: value of alwaysShowPostNav

    Whether links to the previous and next docs appear at the bottom of this doc.

  • showSidebar

    optional    boolean
    default: value of alwaysShowSidebar

    Whether the sidebar should appear for this doc.

  • showTOC

    optional    boolean
    default: value of alwaysShowTOC

    Whether the standalone table of contents (the TOC component) should appear for this doc.

Post example

JavaScript
---
title: Title for your doc
shortTitle: Alternate (shorter) title used in navigation
description: Brief description of the doc (used in metadata and search index)
showTOC: false
showPostNav: false
---
## The first header should be an h2
This doc will not show previous/next navigation or a table of contents since `showPostNav`
and `showTOC` are set to `false`.
©2020 K. A. BartoloGatsby theme: Chicago Docs