Customization

Site metadata

You can customize your site's metadata via the siteMetadata object in gatsby-config.js:

// gatsby-config.js
module.exports = {
  siteMetadata: {
    // Used for page titles and SEO
    title: 'My Site',
    // Used in the header
    shortName: 'My Site',
    // Used for the main link and the logo link in the header
    header: {
      title: 'Primer',
      url: 'https://primer.style',
      logoUrl: 'https://primer.style',
    },
    // Used for SEO
    description: 'My site description',
    // Used for social previews
    imageUrl: 'https://user-images.githubusercontent.com/example-image.png',
  },
}

Side navigation

Side navigation for your site is generated from the content in src/@primer/gatsby-theme-doctocat/nav.yml. Edit that file to customize your side navigation. Each entry in nav.yml should have a title and either a url or a children list to create a group of links:

# src/@primer/gatsby-theme-doctocat/nav.yml
- title: Example
  children:
    - title: Example 2
      url: /example/example-2

Entries with children cannot also have a url.

Repository

Doctocat has a few features that rely on information about your repository, including:

• "Edit this page on GitHub" links on the bottom of every page
• Contributors on the bottom of every page
• Repository link in the sidebar

To enable these features, you'll need to specify your site's repository in package.json:

// package.json
{
  "repository": "repo-owner/repo-name"
}

Subdirectories

If your site is located in a subdirectory of a repository, you'll also need to provide the relative path to the root of your git repository via the repoRootPath option in gatsby-config.js:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: '@primer/gatsby-theme-doctocat',
      options: {
        repoRootPath: '..', // defaults to '.'
      },
    },
  ],
}

Default branch

If your site uses a branch other than master for your default branch, you'll also need to let Doctocat know via the defaultBranch option in gatsby-config.js:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: '@primer/gatsby-theme-doctocat',
      options: {
        defaultBranch: 'main', // defaults to 'master'
      },
    },
  ],
}

Contributors

If you have the repository in package.json and repoRootPath in gatsby-config.js set up correctly (as described above), Doctocat will automatically display contributors on the bottom of every page, like so:

2 contributors

Last edited by colebemis on August 15, 2019

These contributors are determined by commits. However, we know that commits aren't the only way to contribute. You can use front matter to give credit to people who aren't listed in the commit history but still contributed.

Hero

To add a hero section to a page, you'll need to override the default layout component with Doctocat's HeroLayout component by exporting it from your MDX file:

// index.mdx
import {HeroLayout} from '@primer/gatsby-theme-doctocat'
export default HeroLayout

HeroLayout is similar to the default layout component except it also renders a Hero component displaying the title and description defined in the siteMetadata object from gatsby-config.js:

<Hero />

To use a custom hero component, shadow Doctocat's default Hero component by creating a hero.js file in src/@primer/gatsby-theme-doctocat/components:

// src/@primer/gatsby-theme-doctocat/components/hero.js
import {Box} from '@primer/react'
import React from 'react'

export default function Hero() {
  return (
    <Box bg="black" p={5}>
      My Custom Hero
    </Box>
  )
}

Favicon

If you want to override the default favicon, you can pass a relative path to a custom icon as a theme option in your gatsby-config.js:

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: '@primer/gatsby-theme-doctocat',
      options: {
        icon: './src/images/custom-icon-512.png', // This path is relative to the root of the site.
      },
    },
  ],
}

Doctocat uses gatsby-plugin-manifest to generate a pre-configured set of icons from your image. For best results, if you’re providing an icon for generation, it should be:

• 512x512 pixels or larger.
• Square. If it’s not, the image will be letterboxed with a transparent background.
• JPEG, PNG, WebP, TIFF, GIF, or SVG format.

MDX components

Doctocat uses MDX to allow you to embed React components in your markdown files and provides a few React components that are globally available in all .md and .mdx files (no import required). To add custom components to this list of globally available components, create an mdx-components.js file in src/@primer/gatsby-theme-doctocat/ and export your custom components from this file:

// src/@primer/gatsby-theme-doctocat/mdx-components.js
import {SomeComponent} from 'path/to/some-component'

export default {
  SomeComponent,
}

---
title: Some markdown file
---

You can now use your component in any markdown file like so:

<SomeComponent />