Getting started

This guide will walk you through creating, customizing, and deploying a new site with Doctocat using our template repository. If you have an existing repository where you would like to create a new site, we recommend using the Gatsby CLI instead. Check out the Gatsby CLI guide for more information.

1. Create a new repository from the template

Use the Doctocat template to create a new repository. See "Creating a repository from a template" for more information about using template repositories.

Let's check out the directory structure of your new repository:

.
├── gatsby-config.js
├── content/
├── src/
│   └── @primer/
│       └── gatsby-theme-doctocat
├── package.json
└── now.json

• gatsby-config.js: This is your Gatsby configuration, where you can specify information about your site (such as title and description), and any additional Gatsby plugins.
• content/: This is where you will spend most of your time writing documentation. Markdown files (.md or .mdx) in content/ will be interpreted as MDX, a combination of standard Markdown and React JSX. Each document becomes a page on your site with a URL based on its path relative to content/.
• src/: This directory will contain any supporting files such as assets and custom React components.
  • @primer/gatsby-theme-doctocat/: You can use this directory to customize the look and behavior of the theme. All files placed in this directory will "shadow" files in the src directory of the Doctocat theme. Check out "What is Component Shadowing?" for more information.
• package.json: This file contains metadata like the project's name, repository, and a list of packages the project depends on. Check out the package.json docs for more information.
• now.json: When using Now to deploy, the configuration for your deployment is read from this file. Check out the now.json docs for more information. Feel free to delete this file if you don't plan to deploy your site or want to use a different deployment service, like Netlify or Surge.

2. Update your site metadata

After you've created the repository, you'll want to customize the information about your site. Start by replacing the site metadata in the gatsby-config.js file:

module.exports = {
  siteMetadata: {
-   title: 'Doctocat Template',
-   shortName: 'Doctocat Template',
-   header: {
-     title: 'Primer',
-     url: 'https://primer.style',
-     logoUrl: 'https://primer.style'
-   },
-   description: 'A Doctocat template site.',
+   title: 'My Site', // Used for the page titles and SEO
+   shortName: 'My Site', // Used in the header
+   header: {
+     title: 'My Home', // Used for the first link in the header. If you leave it empty ('') the link will not be rendered
+     url: 'https://www.my-home.com', // Used for the first link in the header
+     logoUrl: 'https://www.my-home.com' // Used for the link in the logo in the header
+   },
+   description: 'My site description.', // Used for SEO
  },
  ...
}

Next, open the package.json file and update the name and repository field:

{
- "name": "doctocat-template",
- "repository": "primer/doctocat-template",
+ "name": "my-site",
+ "repository": "my-username/my-site",
  ...
}

Note: Doctocat uses the repository field in package.json as well as the repoRootPath theme option in gatsby-config.js to generate edit links for every page.

You'll also want to update the name field in the now.json file:

{
- "name": "doctocat-template"
+ "name": "my-site"
  ...
}

3. Add your content

Next, go ahead and put your Markdown documents (.md or .mdx) in content/. Documents in content/ automatically become pages with URLs based on their path relative to content/. For example, if you create a content/components/box.md file, Doctocat will use that file to create a /components/box page.

4. Update your side navigation

Side navigation for your site is generated from the content in src/@primer/gatsby-theme-doctocat/nav.yml. After you've put your documents in content/, update the nav.yml file accordingly:

- title: Example
  url: '/example'
  items:
    - title: Example 2
      url: '/example/example-2'

5. Deploy to GitHub Pages

After you've customized the content of your site, you're ready to deploy. There are many ways to deploy your site, but we currently use GitHub Pages for most of our sites, and have found it to be an easy way to get sites up and running quickly.

6. Add a primer.style path alias

To make your site available from primer.style/my-site, please reach out to #primer on Slack with your requirements. In the meantime, check out "Adding a primer.style path alias" in the Deployment guide.

What's next?

Check out the customization guide.