You can customize your site's metadata via the siteMetadata
object in gatsby-config.js
:
// gatsby-config.jsmodule.exports = {siteMetadata: {// Used for page titles and SEOtitle: 'My Site',// Used in the headershortName: 'My Site',// Used for the main link and the logo link in the headerheader: {title: 'Primer',url: 'https://primer.style',logoUrl: 'https://primer.style',},// Used for SEOdescription: 'My site description',// Used for social previewsimageUrl: 'https://user-images.githubusercontent.com/example-image.png',},}
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: Examplechildren:- title: Example 2url: /example/example-2
Entries with children
cannot also have a url
.
Doctocat has a few features that rely on information about your repository, including:
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 repository via the repoRootPath
option in gatsby-config.js
:
// gatsby-config.jsmodule.exports = {plugins: [{resolve: '@primer/gatsby-theme-doctocat',options: {repoRootPath: '..', // defaults to '.'},},],}
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.jsmodule.exports = {plugins: [{resolve: '@primer/gatsby-theme-doctocat',options: {defaultBranch: 'main', // defaults to 'master'},},],}
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:
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.
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.mdximport {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.jsimport {Box} from '@primer/react'import React from 'react'export default function Hero() {return (<Box bg="black" p={5}>My Custom Hero</Box>)}
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.jsmodule.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:
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.jsimport {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 />