Skip to content

Customization

Here are a few ways you can customize your Doctocat site:

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 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, url, and an optional children list to create nested navigation links:

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

Note: Doctocat only supports one level of nesting.

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"
}

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 respository via the repoRootPath option in gatsby-config.js:

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

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 contributorscolebemisemplums
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:

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/components'
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.
Edit this page on GitHub
2 contributorsjpvalerycolebemis
Last edited by jpvalery on July 10, 2020