@kabartolo/gatsby-theme-chicago-docs-core v1.2.0

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.

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.

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.

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