{"data":{"allMdx":{"nodes":[{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/components/caption.mdx","frontmatter":{"title":"Caption"},"rawBody":"---\ntitle: Caption\nstatus: New\nsource: https://github.com/primer/doctocat/blob/master/theme/src/components/caption.js\ncomponentId: caption\na11yReviewed: true\ndescription: A caption component for images and other media content with a light gray background and a small font size for additional information.\n---\n\nThe caption component can be used to append a caption to images used in documentation.\n\n## Usage\n\n`Caption` is a [shortcode](https://mdxjs.com/blog/shortcodes), meaning it's globally available in all `.md` and `.mdx` files. So you can use the `Caption` component in any `.md` or `.mdx` file without importing it.\n\n## Example\n\n```jsx live\n\n \n
A beautiful husky puppy.
\n\n```\n\n\n\n\nBe sure to provide enough detail in your caption so users with assistive technology have adequate context. An empty alt tag `alt=\"\"` should be used on the `img` in cases where the caption describes the image, thus making the image decorative in purpose.\n\n\n\n","parent":{"__typename":"File","relativeDirectory":"components","name":"caption"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/components/do-dont.mdx","frontmatter":{"title":"Do/Don't"},"rawBody":"---\ntitle: Do/Don't\nstatus: New\nsource: https://github.com/primer/doctocat/blob/master/theme/src/components/do-dont.js\n---\n\nUse the `Do` and `Dont` components to provide good and bad examples within documentation.\n\n## Usage\n\n`Do`, `Dont` and `DoDontContainer` are a [shortcodes](https://mdxjs.com/blog/shortcodes), meaning they are globally available in all `.md` and `.mdx` files. So you can use the `Do`, `Dont`, and `DoDontContainer` components in any `.md` or `.mdx` file without importing them.\n\n### Side-by-side\n\nTo create a side-by-side Do/Don't example, wrap the `Do` and `Dont` components with the `DoDontContainer` component:\n\n```jsx live\n\n \n \n
Use brief and direct communication
\n \n \n \n
Don't use wordy and redundant copy
\n \n\n```\n\n_Note: Caption text should describe the image and be able to stand on its own. The `alt` prop should be used if a more detailed description of the image is needed._\n\n### Stacked\n\nThe `DoDontContainer` component also accepts a `stacked` prop to create stacked Do/Don't examples:\n\n```jsx live\n\n \n \n
Use a container class to give the text a max-width
\n \n \n \n
Don't let the text span the entire width of the window
\n \n\n```\n\n### Indented\n\n`Do` and `Dont` components can also be indented to increase the clarity of the example message within the documentation:\n\n```jsx live\n\n \n Place pane regions on the left to display navigation, filtering, or an\n overview for entities such as users, bots, apps, etc.\n \n \n Don't display more than three columns of information on a page.\n \n\n```\n","parent":{"__typename":"File","relativeDirectory":"components","name":"do-dont"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/components/image-container.mdx","frontmatter":{"title":"ImageContainer"},"rawBody":"---\ntitle: ImageContainer\nstatus: New\nsource: https://github.com/primer/doctocat/blob/master/theme/src/components/image-container.js\n---\n\nUse the `ImageContainer` component to contain images in documentation pages.\n\n## Usage\n\n`ImageContainer` is a [shortcode](https://mdxjs.com/blog/shortcodes), meaning it's globally available in all `.md` and `.mdx` files. So you can use the `ImageContainer` component in any `.md` or `.mdx` file without importing it.\n\n```jsx live\n\n \n\n
Star and Unstar buttons
\n```\n","parent":{"__typename":"File","relativeDirectory":"components","name":"image-container"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/components/index.mdx","frontmatter":{"title":"Components"},"rawBody":"---\ntitle: Components\n---\n\nDoctocat provides a collection of React components that are globally available in all `.md` and `.mdx` files (no import required).\n","parent":{"__typename":"File","relativeDirectory":"components","name":"index"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/components/note.mdx","frontmatter":{"title":"Note"},"rawBody":"---\ntitle: Note\nstatus: New\nsource: https://github.com/primer/doctocat/blob/master/theme/src/components/note.js\ncomponentId: note\n---\n\nUse the `Note` component to call out information in documentation pages.\n\n## Usage\n\n`Note` is a [shortcode](https://mdxjs.com/blog/shortcodes), meaning it's globally available in all `.md` and `.mdx` files. So you can use the `Note` component in any `.md` or `.mdx` file without importing it.\n\n```jsx live\nYour note goes here\n```\n\nTo write markdown syntax inside of a `Note`, make sure to add extra newlines to separate the content from the opening and\nclosing tags:\n\n```\nblah blah blah\n\n\n\nYour _note_ goes **here**.\n\n\n\nblah blah blah\n```\n\n## Variants\n\n### Info (default)\n\nUse the `info` variant to call out neutral information.\n\n```jsx live\nYour note goes here\n```\n\n### Warning\n\nUse the `warning` variant to indicate that extra care should be taken.\n\n```jsx live\nDon't forget to give your images alt text.\n```\n\n### Danger\n\nUse the `danger` variant to indicate that something bad could happen if the reader ignores the note.\n\n```jsx live\nDon't cut the red wire!\n```\n","parent":{"__typename":"File","relativeDirectory":"components","name":"note"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/contributing.mdx","frontmatter":{"title":"Contributing"},"rawBody":"---\ntitle: Contributing\n---\n\nWe appreciate your contribution and hope that this document helps you along the way. If you have any questions or problems, don't hesitate to [file an issue](https://github.com/primer/doctocat/issues/new).\n\n\n\n\nThese guidelines are for contributing to the theme itself, if you are looking for help running a Doctocat site for another project locally, check out the [Local Development](/usage/local-development) docs in the Usage section.\n\n\n\n\n## Local development\n\nRun the following commands to begin local development:\n\n\n\n\nThese steps require [Node.js](https://nodejs.org) and [Yarn](https://yarnpkg.com) to be set up locally.\n\n\n\n\n```shell\n# Clone the repository\ngit clone https://github.com/primer/doctocat.git\ncd doctocat\n\n# Install the dependencies\nyarn\n\n# Start the development server for the documentation site\nyarn workspace docs develop\n\n# Navigate to http://localhost:8000 in your browser\n```\n\n## File structure\n\n```\n.\n├── theme/\n├── docs/\n├── package.json\n└── now.json\n```\n\n- `theme/`: This directory contains the code for the [Gatsby Theme](https://www.gatsbyjs.org/docs/themes/what-are-gatsby-themes/) and is what gets published to npm.\n- `docs/`: This directory contains the code for the documentation site for Doctocat. The documentation site can also be used to test changes to the theme locally.\n- `package.json`: This file defines the [Yarn Workspaces](https://yarnpkg.com/lang/en/docs/workspaces/) for the project and is not meant to be published.\n- `now.json`: This file configures the deployment of the documentation site. Check out the [now.json docs](https://zeit.co/docs/v2/deployments/configuration/?query=now.json) for more information.\n\n## Scripts\n\nThe documentation site has a few [npm scripts](https://docs.npmjs.com/misc/scripts) for developing and building the site. You can run these scripts from the root directory using the [`yarn workspace`](https://yarnpkg.com/lang/en/docs/cli/workspace/) command:\n\n```shell\nyarn workspace docs \n```\n\n### `develop`\n\nStarts Gatsby's hot-reloading development environment on http://localhost:8000. This is likely the only script you will run manually.\n\n### `build`\n\nBuilds the site for deployment and places the output in `public/`.\n\n### `now-build`\n\nBuilds the site for [Now](https://zeit.co/now) deployment. You will never have to run `now-build` manually. Check out the [`@now/static-build` docs](https://zeit.co/docs/v2/advanced/builders/static-build-now-static-build) for more information.\n\n## Bug reports\n\nGuidelines for bug reports:\n\n1. Use the GitHub issue search – check if the issue has already been reported.\n2. Check if the issue has been fixed – try to reproduce it using the latest version of the extension.\n3. Isolate the problem – find a way to demonstrate your issue. Provide either screenshots or code samples to show you problem.\n\nA good bug report shouldn't leave others needing to chase you down for more information. Please try to be as detailed as possible in your report.\n\n- What is your environment?\n- What steps will reproduce the issue?\n- What browser(s) versions experience the problem?\n- What would you expect to be the outcome?\n\nAll these details will help people to fix any potential bugs.\n\nExample:\n\n> Short and descriptive example bug report title\n>\n> A summary of the issue and the browser/OS environment in which it occurs. If suitable, include the steps required to reproduce the bug.\n>\n> 1. This is the first step\n> 2. This is the second step\n> 3. Further steps, etc.\n> 4. Attach screenshots, etc.\n>\n> Any other information you want to share that is relevant to the issue being reported.\n\n## Feature requests\n\nFeature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to _you_ to make a strong case to convince the project's developers of the merits of this feature.\nPlease provide as much detail and context as possible.\n\n## Pull requests\n\nGood pull requests - patches, improvements, new features - are a fantastic help.\nThey should remain focused in scope and avoid containing unrelated commits.\n\n**Please ask first** before embarking on any significant pull request (e.g. implementing features, refactoring code),\notherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project.\n\nPlease adhere to the coding conventions used throughout a project (indentation, accurate comments, etc.) and any other requirements (such as test coverage).\n\nFollow this process if you'd like your work considered for inclusion in the project:\n\n- [Fork](http://help.github.com/fork-a-repo/) the project, clone your fork, and configure the remotes:\n\n ```shell\n # Clone your fork of the repository\n git clone https://github.com//doctocat\n\n # Navigate to the newly cloned directory\n cd doctocat\n\n # Assign the original repo to a remote called \"upstream\"\n git remote add upstream https://github.com/primer/doctocat\n ```\n\n- If you cloned a while ago, get the latest changes from upstream:\n\n ```shell\n git checkout master\n git pull upstream master\n ```\n\n- Create a new topic branch (off of the `master` branch) to contain your feature, change, or fix:\n\n ```shell\n git checkout -b \n ```\n\n- Install the dependencies:\n\n ```shell\n yarn\n ```\n\n- Start Gatsby's hot-reloading development environment:\n\n ```shell\n yarn workspace docs develop\n # The documentation site will now be accessible from http://localhost:8000\n ```\n\n- Commit your changes in logical chunks. You can use Git's [interactive rebase](https://help.github.com/articles/interactive-rebase) feature to tidy up your commits before making them public.\n\n- Locally merge (or rebase) the upstream development branch into your topic branch:\n\n ```shell\n git pull [--rebase] upstream master\n ```\n\n- Push your topic branch up to your fork:\n\n ```shell\n git push origin \n ```\n\n- [Open a Pull Request](https://help.github.com/articles/using-pull-requests/) with a clear title and description.\n","parent":{"__typename":"File","relativeDirectory":"","name":"contributing"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/index.mdx","frontmatter":{"title":"Doctocat"},"rawBody":"---\ntitle: Doctocat\n---\n\nimport {HeroLayout} from '@primer/gatsby-theme-doctocat'\n\nexport default HeroLayout\n\nDoctocat makes it easy to set up a documentation site so you can focus on what's important: _writing docs_.\n\n## Resources\n\n- [Getting started](/getting-started)\n- [Contributing](/contributing)\n- [GitHub](https://github.com/primer/doctocat)\n","parent":{"__typename":"File","relativeDirectory":"","name":"index"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/getting-started/gatsby-cli.mdx","frontmatter":{"title":"Gatsby CLI"},"rawBody":"---\ntitle: Gatsby CLI\n---\n\nFollow these steps to create a new site using the [Gatsby CLI](https://www.gatsbyjs.org/docs/gatsby-cli/):\n\n\n\n\nThis guide assumes that you have some familiarity with the command line, and have Node.js and npm installed locally. Check out [nodejs.org](https://nodejs.org) for more information. You will need npm v5.2.0 or higher to use the [`npx`](https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner) command in step 1.\n\n\n\n\n## 1. Scaffold a new site\n\nUse the Gatsby CLI and the Doctocat starter to scaffold a new site:\n\n```shell\nnpx gatsby new my-site https://github.com/primer/doctocat-starter\n```\n\n`my-site` is an arbitrary title — you can pick anything. Running the above command will place the code for your new site in a new directory called “my-site”. If you want to create a new site in an existing repository, be sure to run the `gatsby new` command from within that repository.\n\n## 2. Navigate into the site directory\n\nNavigate into the newly created site directory using `cd`:\n\n```shell\ncd my-site\n```\n\nCheck out the [getting started guide](/getting-started) for more information about the important files and subdirectories in your new site directory.\n\n## 3. Start the development server\n\nUse the `develop` npm script to start Gatsby's hot-reloading development environment:\n\n```shell\nnpm run develop\n```\n\nTo view your site locally, navigate to http://localhost:8000 in your browser. Each page of the site corresponds to a file in the `content` directory. Navigate to any page then try editing the corresponding MDX file. You should see the page update in real time.\n\n## What's next?\n\nCheck out the [customization](/usage/customization) and [deployment](/usage/deployment) guides.\n","parent":{"__typename":"File","relativeDirectory":"getting-started","name":"gatsby-cli"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/getting-started/index.mdx","frontmatter":{"title":"Getting started"},"rawBody":"---\ntitle: Getting started\nadditionalContributors:\n - ashygee\n - emplums\n - shawnbot\n---\n\nThis guide will walk you through creating, customizing, and deploying a new site with Doctocat using our [template repository](https://github.com/primer/doctocat-template). 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](/getting-started/gatsby-cli) for more information.\n\n## 1. Create a new repository from the template\n\nUse the [Doctocat template](https://github.com/primer/doctocat-starter) to create a new repository. See \"[Creating a repository from a template](https://help.github.com/en/articles/creating-a-repository-from-a-template)\" for more information about using template repositories.\n\n\n\nLet's check out the directory structure of your new repository:\n\n```\n.\n├── gatsby-config.js\n├── content/\n├── src/\n│ └── @primer/\n│ └── gatsby-theme-doctocat\n├── package.json\n└── now.json\n```\n\n- `gatsby-config.js`: This is your [Gatsby configuration](https://www.gatsbyjs.org/docs/gatsby-config/), where you can specify information about your site (such as title and description), and any additional [Gatsby plugins](https://www.gatsbyjs.org/plugins/).\n- `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](https://mdxjs.com/), a combination of standard Markdown and [React JSX](https://reactjs.org/docs/jsx-in-depth.html). Each document [becomes a page](https://www.gatsbyjs.org/docs/recipes/#creating-pages) on your site with a URL based on its path relative to `content/`.\n- `src/`: This directory will contain any supporting files such as assets and custom React components.\n - `@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?](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/)\" for more information.\n- `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](https://docs.npmjs.com/files/package.json) for more information.\n- `now.json`: When using [Now](https://zeit.co/now) to deploy, the configuration for your deployment is read from this file. Check out the [now.json docs](https://zeit.co/docs/v2/deployments/configuration/?query=now.json) 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](https://www.netlify.com/) or [Surge](https://surge.sh/).\n\n## 2. Update your site metadata\n\nAfter 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:\n\n```diff\nmodule.exports = {\n siteMetadata: {\n- title: 'Doctocat Template',\n- shortName: 'Doctocat Template',\n- header: {\n- title: 'Primer',\n- url: 'https://primer.style',\n- logoUrl: 'https://primer.style'\n- },\n- description: 'A Doctocat template site.',\n+ title: 'My Site', // Used for the page titles and SEO\n+ shortName: 'My Site', // Used in the header\n+ header: {\n+ title: 'My Home', // Used for the first link in the header. If you leave it empty ('') the link will not be rendered\n+ url: 'https://www.my-home.com', // Used for the first link in the header\n+ logoUrl: 'https://www.my-home.com' // Used for the link in the logo in the header\n+ },\n+ description: 'My site description.', // Used for SEO\n },\n ...\n}\n```\n\nNext, open the `package.json` file and update the `name` and `repository` field:\n\n```diff\n{\n- \"name\": \"doctocat-template\",\n- \"repository\": \"primer/doctocat-template\",\n+ \"name\": \"my-site\",\n+ \"repository\": \"my-username/my-site\",\n ...\n}\n```\n\n_Note: Doctocat uses the [`repository`](https://docs.npmjs.com/files/package.json#repository) field in `package.json` as well as the [`repoRootPath` theme option](/theme-options) in `gatsby-config.js` to generate edit links for every page._\n\nYou'll also want to update the `name` field in the `now.json` file:\n\n```diff\n{\n- \"name\": \"doctocat-template\"\n+ \"name\": \"my-site\"\n ...\n}\n```\n\n## 3. Add your content\n\nNext, 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.\n\n## 4. Update your side navigation\n\nSide 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:\n\n```yml\n- title: Example\n url: '/example'\n items:\n - title: Example 2\n url: '/example/example-2'\n```\n\n## 5. Deploy to GitHub Pages\n\nAfter 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](https://pages.github.com/) for most of our sites, and have found it to be an easy way to get sites up and running quickly.\n\n## 6. Add a primer.style path alias\n\nTo 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](/usage/deployment#adding-a-primer.style-path-alias)\" in the [Deployment](/usage/deployment) guide.\n\n## What's next?\n\nCheck out the [customization](/usage/customization) guide.\n","parent":{"__typename":"File","relativeDirectory":"getting-started","name":"index"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/usage/customization.mdx","frontmatter":{"title":"Customization"},"rawBody":"---\ntitle: Customization\ndescription: Here are a few ways you can customize your Doctocat site.\n---\n\nimport {Box} from '@primer/react'\nimport {Contributors} from '@primer/gatsby-theme-doctocat'\n\n## Site metadata\n\nYou can customize your site's metadata via the `siteMetadata` object in `gatsby-config.js`:\n\n```js\n// gatsby-config.js\nmodule.exports = {\n siteMetadata: {\n // Used for page titles and SEO\n title: 'My Site',\n // Used in the header\n shortName: 'My Site',\n // Used for the main link and the logo link in the header\n header: {\n title: 'Primer',\n url: 'https://primer.style',\n logoUrl: 'https://primer.style',\n },\n // Used for SEO\n description: 'My site description',\n // Used for social previews\n imageUrl: 'https://user-images.githubusercontent.com/example-image.png',\n },\n}\n```\n\n## Side navigation\n\nSide 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:\n\n```yml\n# src/@primer/gatsby-theme-doctocat/nav.yml\n- title: Example\n children:\n - title: Example 2\n url: /example/example-2\n```\n\nEntries with `children` cannot also have a `url`.\n\n\n Doctocat supports a maximum of two levels of nesting.\n\n\n## Repository\n\nDoctocat has a few features that rely on information about your repository, including:\n\n- \"Edit this page on GitHub\" links on the bottom of every page\n- Contributors on the bottom of every page\n- Repository link in the sidebar\n\nTo enable these features, you'll need to specify your site's [`repository`](https://docs.npmjs.com/files/package.json#repository) in `package.json`:\n\n```json\n// package.json\n{\n \"repository\": \"repo-owner/repo-name\"\n}\n```\n\n## Subdirectories\n\nIf 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`:\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: '@primer/gatsby-theme-doctocat',\n options: {\n repoRootPath: '..', // defaults to '.'\n },\n },\n ],\n}\n```\n\n## Default branch\n\nIf 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`:\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: '@primer/gatsby-theme-doctocat',\n options: {\n defaultBranch: 'main', // defaults to 'master'\n },\n },\n ],\n}\n```\n\n## Contributors\n\nIf you have the `repository` in `package.json` and `repoRootPath` in `gatsby-config.js` set up correctly (as described [above](#edit-on-github-link)), Doctocat will automatically display contributors on the bottom of every page, like so:\n\n\n \n\n\nThese contributors are determined by commits. However, we know that commits aren't the only way to contribute. You can use [front matter](/usage/front-matter#additional-contributors) to give credit to people who aren't listed in the commit history but still contributed.\n\n## Hero\n\nTo 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:\n\n```markdown\n// index.mdx\nimport {HeroLayout} from '@primer/gatsby-theme-doctocat'\nexport default HeroLayout\n```\n\n`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`:\n\n```jsx live\n\n```\n\nTo use a custom hero component, [shadow](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/) Doctocat's default `Hero` component by creating a `hero.js` file in `src/@primer/gatsby-theme-doctocat/components`:\n\n```jsx\n// src/@primer/gatsby-theme-doctocat/components/hero.js\nimport {Box} from '@primer/react'\nimport React from 'react'\n\nexport default function Hero() {\n return (\n \n My Custom Hero\n \n )\n}\n```\n\n## Favicon\n\nIf 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`:\n\n```js\n// gatsby-config.js\nmodule.exports = {\n plugins: [\n {\n resolve: '@primer/gatsby-theme-doctocat',\n options: {\n icon: './src/images/custom-icon-512.png', // This path is relative to the root of the site.\n },\n },\n ],\n}\n```\n\nDoctocat uses [`gatsby-plugin-manifest`](https://www.gatsbyjs.org/packages/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:\n\n- 512x512 pixels or larger.\n- Square. If it’s not, the image will be [letterboxed]() with a transparent background.\n- JPEG, PNG, WebP, TIFF, GIF, or SVG format.\n\n## MDX components\n\nDoctocat uses [MDX](https://mdxjs.com/) to allow you to embed React components in your markdown files and provides a few React [components](/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:\n\n```js\n// src/@primer/gatsby-theme-doctocat/mdx-components.js\nimport {SomeComponent} from 'path/to/some-component'\n\nexport default {\n SomeComponent,\n}\n```\n\n```md\n---\ntitle: Some markdown file\n---\n\nYou can now use your component in any markdown file like so:\n\n\n```\n","parent":{"__typename":"File","relativeDirectory":"usage","name":"customization"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/usage/deployment.mdx","frontmatter":{"title":"Deployment"},"rawBody":"---\ntitle: Deployment\n---\n\nWhen you build your Doctocat site using [`gatsby build`](https://www.gatsbyjs.org/docs/gatsby-cli/#build), the output is static content: HTML, CSS, JavaScript, images, etc. Static content is incredibly easy and affordable to host with any deployment solution. We have landed on using [Now](https://zeit.co/now) for our deploys.\n\n## Deploying to Now\n\nIf you started with the [Doctocat template](https://github.com/primer/doctocat-template), your site is already configured to deploy with Now. You're ready to set up the [Now for GitHub](https://zeit.co/github) integration. If you did not start with the Doctocat template, before you set up the Now for Github integration, you'll need to create a `now.json` file and add a `now-build` script to `package.json`:\n\n```json\n// now.json\n{\n \"version\": 2,\n \"name\": \"my-site\",\n \"builds\": [\n {\n \"src\": \"package.json\",\n \"use\": \"@now/static-build\",\n \"config\": {\"distDir\": \"public\"}\n }\n ]\n}\n```\n\n```json\n// package.json\n{\n \"scripts\": {\n ...\n \"build\": \"gatsby build\",\n \"now-build\": \"npm run build\"\n }\n}\n```\n\nOnce your site has the necessary configuration files and scripts, you can enable the Now for GitHub integration. You'll need to create a Now account, connect your GitHub account, then enable the integration for your repository. Check out the [Now for GitHub docs](https://zeit.co/docs/v2/integrations/now-for-github/) for more detailed instructions.\n\nAfter you have the GitHub integration set up, you should be able to access your site from a prefixed `.now.sh` domain.\n\n## Deploying to other providers\n\nCheck out Gatsby's [Deploying and Hosting](https://www.gatsbyjs.org/docs/deploying-and-hosting/) guides for more information about deploying to other providers.\n\n## Adding a primer.style path alias\n\n### 1. Update gatsby-config.js\n\nTo make your site available from `primer.style/my-site`, start by setting a [`pathPrefix`](https://www.gatsbyjs.org/docs/path-prefix/) in your `gatsby-config.js`:\n\n```diff\n// gatsby-config.js\nmodule.exports = {\n+ pathPrefix: '/my-site',\n}\n```\n\n### 2. Update package.json\n\nNext, make sure your `build` script in `package.json` runs `gatsby build` with the `--prefix-paths` flag:\n\n```diff\n// package.json\n{\n \"scripts\": {\n- \"build\": \"gatsby build\",\n+ \"build\": \"gatsby build --prefix-paths\",\n \"now-build\": \"npm run build\"\n }\n}\n```\n\nIf this flag is not set, Gatsby will ignore your `pathPrefix`.\n\n### 3. Update now.json\n\nThe `--prefix-paths` flag tells Gatsby to prefix paths used in the [`Link`](https://www.gatsbyjs.org/docs/gatsby-link/) component and [`navigate`](https://www.gatsbyjs.org/docs/gatsby-link/#how-to-use-the-navigate-helper-function) helper with the `pathPrefix` value assigned in your `gatsby-config.js` file. However, `--prefix-paths` doesn't change where built files get stored in the build directory. This creates a mismatch between the links on your site and the actual paths to your files.\n\nTo fix this issue, you'll need to define a [route](https://zeit.co/docs/v2/advanced/routes) in your `now.json` file that proxies `/my-site/*` to `/*` so that behind the scenes a path like `/my-site/getting-started` will find `/getting-started.html` in your build directory:\n\n```json\n// now.json\n{\n ...\n \"routes\": [\n {\"src\": \"/my-site(/.*)?\", \"dest\": \"$1\"},\n ]\n}\n```\n\nIf your site is located in a subdirectory, make sure the destination (`dest`) of your proxy route is the path to that subdirectory followed by `$1`. Here's what your `now.json` file might look like if your site is located in a subdirectory called `docs`:\n\n```json\n// now.json\n{\n ...\n \"routes\": [\n {\"src\": \"/my-site(/.*)?\", \"dest\": \"/docs$1\"},\n ]\n}\n```\n\nIn order to route branch deploys correctly, you'll also need to set up a route that redirects root route requests (`my-site.now.sh`) to your path prefix (`my-site.now.sh/my-site`):\n\n```diff\n// now.json\n{\n ...\n \"routes\": [\n {\"src\": \"/my-site(/.*)?\", \"dest\": \"/docs$1\"},\n+ {\n+ \"src\": \"/\",\n+ \"status\": 301,\n+ \"headers\": {\"Location\": \"/my-site\"}\n+ }\n ]\n}\n```\n\nThis is necessary because when your project lives in a subdirectory, there isn't any content for the site in the root of your deploy.\n\n### 4. Update now.json in primer/primer.style\n\nAfter everything is set up in your repository, open a pull request on the [primer/primer.style](https://github.com/primer/primer.style) repository to add your site to the `routes` list in [now.json](https://github.com/primer/primer.style/blob/master/now.json):\n\n```diff\n// now.json in primer/primer.style\n{\n \"routes\": [\n {\"src\": \"/components(/.*)?\", \"dest\": \"https://primer-components.now.sh\"},\n {\"src\": \"/css(/.*)?\", \"dest\": \"https://primer-css.now.sh\"},\n {\"src\": \"/design(/.*)?\", \"dest\": \"https://primer-design.now.sh\"},\n {\"src\": \"/blueprints(/.*)?\", \"dest\": \"https://primer-blueprints.now.sh\"},\n {\"src\": \"/presentations(/.*)?\", \"dest\": \"https://primer-presentations.now.sh\"},\n+ {\"src\": \"/my-site(/.*)?\", \"dest\": \"https://my-site.now.sh\"}\n ]\n}\n```\n\nOnce your pull request is approved and merged, you'll be able to access your site from `primer.style/my-site`. 🎉\n","parent":{"__typename":"File","relativeDirectory":"usage","name":"deployment"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/usage/front-matter.mdx","frontmatter":{"title":"Front matter"},"rawBody":"---\ntitle: Front matter\n---\n\nimport {Box} from '@primer/react'\nimport {StatusLabel} from '@primer/gatsby-theme-doctocat'\nimport StorybookLink from '@primer/gatsby-theme-doctocat/src/components/storybook-link'\nimport LookbookLink from '@primer/gatsby-theme-doctocat/src/components/lookbook-link'\nimport SourceLink from '@primer/gatsby-theme-doctocat/src/components/source-link'\n\n\nWhen you create a Markdown file (`.md` or `.mdx`) in `src/pages/`, you can define variables to provide additional information about that page. This information is called front matter and is set between triple dashes starting on the first line of the file:\n\n```\n---\ntitle: Example title\n---\n```\n\nDoctocat recognizes some specific front matter variables described below.\n\n## Title and description\n\n`title` is used to render the page heading and generate the [page title](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title). `description` is used to create a [meta description tag](https://moz.com/learn/seo/meta-description) which is important for SEO. We recommend setting `title` and `description` for every page:\n\n```markdown\n---\ntitle: My page title\ndescription: My page description\n---\n```\n\n## Component metadata\n\nTo auto-populate the `title` and `description` of a component page using metadata from the [primer/component-metadata](https://github.com/primer/component-metadat) repository, add the `componentId` frontmatter variable:\n\n```markdown\n---\ncomponentId: avatar\n---\n```\n\n\n\n`componentId` must match the `id` of a component in this [metadata.json](https://github.com/primer/component-metadata/blob/main/metadata.json) file.\n\n\n\n## Status\n\nYou can add a status label to any page by setting a `status` variable in the frontmatter:\n\n```markdown\n---\nstatus: Stable\n---\n```\n\nDoctocat comes with a few predefined statuses that have colors associated with them:\n\n| Status | Output | Meaning |\n| -------------- | ------------------------------------- |------------------------------------------------------------------------|\n| `Alpha` | | Experimental. Breaking changes are likely. |\n| `Beta` | | Usage encouraged, but not required. |\n| `Stable` | | Usage expected. |\n| `Deprecated` | | Usage not allowed. May be removed at any time. |\n\nCustom statuses will render a gray dot:\n\n\n\n## Source\n\nSometimes it's useful to provide quick access to relevant source code. You can use the `source` front matter variable to do that:\n\n```\n---\nsource: https://github.com/path/to/code\n---\n```\n\nIf the `source` front matter variable is defined, Doctocat will add a source code link to the top of the page, like this:\n\n\n \n\n\n\n\n\nThis source code link is not the same as the \"Edit this page on GitHub\" link that is automatically added to the bottom of every page. The source code link should point to code that is relevant to the page. The \"Edit this page on GitHub\" link points to the Markdown file for the page itself.\n\n\n\n## Storybook\n\n You can use the `storybook` front matter variable to link to [Storybook](https://storybook.js.org/) stories:\n\n```\n---\nstorybook: https://primer.style/view-components/stories/?path=/story/primer-avatar-component\n---\n```\n\nIf the `storybook` front matter variable is defined, Doctocat will add a storybook link to the top of the page, like this:\n\n\n \n\n\n\n## Lookbook\n\n You can use the `lookbook` front matter variable to link to [Lookbook](http://lookbook.build/) previews:\n\n```\n---\nlookbook: https://primer.style/view-components/lookbook/inspect/primer/avatar\n---\n```\n\nIf the `lookbook` front matter variable is defined, Doctocat will add a lookbook link to the top of the page, like this:\n\n\n \n\n\n\n## Additional contributors\n\nIf you have the `repository` in `package.json` and `repoRootPath` in `gatsby-config.js` setup correctly (as described in the [customization](/usage/customization#contributors) guide), Doctocat will automatically display contributors on the bottom of every page. These contributors are determined by commits. However, we know that commits aren't the only way to contribute. To give credit to people who aren't listed in the commit history but still contributed, use the `additionalContributors` front matter variable to list their GitHub usernames, for example:\n\n```markdown\n---\nadditionalContributors:\n - ashygee\n - emplums\n---\n```\n","parent":{"__typename":"File","relativeDirectory":"usage","name":"front-matter"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/usage/index.mdx","frontmatter":{"title":"Usage"},"rawBody":"---\ntitle: Usage\n---\n","parent":{"__typename":"File","relativeDirectory":"usage","name":"index"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/usage/live-code.mdx","frontmatter":{"title":"Live code"},"rawBody":"---\ntitle: Live code\n---\n\nDoctocat can render code blocks as live previews with editable code using [react-live](https://github.com/FormidableLabs/react-live). To make a code block render as an editable example, add a `live` attribute after the language:\n\n````markdown\n```jsx live\n\n```\n````\n\nHere's how the above example will render on a page:\n\n```jsx live\n\n```\n\nDoctocat supports live code examples for `jsx` and `html`.\n\n## Scope\n\nBefore you can use components or other variables in live code examples, you'll need to add them to the global scope of live previews. Otherwise, the live previews will display a `ReferenceError`, like this:\n\n```jsx live\n// `Foo` was not added to the global scope of live previews.\nHello, world!\n```\n\nYou can add variables to the global scope of live previews by [shadowing](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/) `src/@primer/gatsby-theme-doctocat/live-code-scope.js`:\n\n```js\n// src/@primer/gatsby-theme-doctocat/live-code-scope.js\nimport {Box} from '@primer/react'\n\nexport default {\n Box,\n text: 'Hello, world!',\n}\n```\n\n\n\n\nMake sure to place `live-code-scope.js` in the root of your `gatsby-theme-doctocat` folder. Shadowed files must be present in the same location as they exist in the theme repository.\n\n\n\n\nEvery property on the object exported by `live-code-scope.js` will be available as a variable in the code:\n\n````markdown\n```jsx live\n{text}\n```\n````\n\n## Line highlighting\n\nIf you want to emphasize a particular range of lines, use the `highlight` attribute on the code block. The expected format is `higlight=start-end`. The line highlighting will disappear when the live example is edited.\n\n\n````markdown\n``` jsx live highlight=2-4\n
\n
\n This paragraph element should be higlighted.\n
\n
\n This paragraph element should not be higlighted.\n
\n
\n```\n````\n\n``` jsx live highlight=2-4\n
\n
\n This paragraph element should be higlighted.\n
\n
\n This paragraph element should not be higlighted.\n
\n
\n```\n\n## Global styles\n\nLive previews are completely isolated from the rest of the page because they are rendered inside [iframes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe). This means that you can apply global styles inside live previews without affecting the rest of the page:\n\n```jsx live\n
\n \n
\n This text should be red. All other text on the page should be unaffected.\n
\n
\n```\n\nYou can apply global styles to _all_ live previews on your site by [shadowing](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/) `live-preview-wrapper.js` with a component that renders a `style` or `link` tag:\n\n```jsx\n// src/@primer/gatsby-theme-doctocat/components/live-preview-wrapper.js\nimport React from 'react'\n\nexport default function LivePreviewWrapper({children}) {\n return (\n
\n \n {children}\n
\n )\n}\n```\n\n## No-inline\n\nBy default, live previews treat your code as a single JSX expression to be rendered. If you want to include more complex code, use the `noinline` attribute on the code block, and render components with the exported `render` function:\n\n````markdown\n```javascript live noinline\nfunction DemoApp() {\n const [count, setCount] = React.useState(0)\n\n return (\n
\n )\n}\n\nrender()\n```","parent":{"__typename":"File","relativeDirectory":"usage","name":"live-code"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/usage/local-development.mdx","frontmatter":{"title":"Local development"},"rawBody":"---\ntitle: Local development\n---\n\nTo run your Doctocat site locally follow these steps:\n\n1. If your site is located in a subfolder of your repository like `/docs`, navigate to that folder in your terminal like so:\n`cd docs`\n\n2. Install dependencies: `yarn`\n\n3. Run `yarn run develop`\n\n4. Go to `localhost:8000` in your browser.\n\nIf these steps don't work, check the README or reach out to the maintainer of the project you're working on. Some Doctocat sites may decide to customize their local development setup.\n","parent":{"__typename":"File","relativeDirectory":"usage","name":"local-development"}},{"fileAbsolutePath":"/home/runner/work/doctocat/doctocat/docs/content/usage/using-images.mdx","frontmatter":{"title":"Using images"},"rawBody":"---\ntitle: Using images\n---\n\nTo use images in your Doctocat site:\n\n1. Add an `images` folder in the root of your docs site\n\n2. Add any images you'd like to use in the `images` folder\n\n3. In the file you'd like to use an image in, import the image using a relative path:\n\n```\nimport DemoImage from '../images/demo-image.png'\n```\n\n4. Then use that image name as the `src` value in an img tag:\n\n```\n\n \n\n```\n\nMake sure to use the `alt` attribute to describe your image for assistive technology, or use the [`Caption` component](/components/caption)\n\nIf you run into any problems with Gatsby building the site and not being able to find your image path try the following:\n\n1. Double check that the path is correct\n2. Try deleting the `./cache` folder and rebuilding\n","parent":{"__typename":"File","relativeDirectory":"usage","name":"using-images"}}]}}}
![](\"https://user-images.githubusercontent.com/586552/63106528-06de5100-bf51-11e9-8a5e-98583ed74874.png\")
\n ![](\"https://user-images.githubusercontent.com/586552/63106527-06de5100-bf51-11e9-858c-72de6a5c728a.png\")
\n ![](\"https://user-images.githubusercontent.com/586552/63046880-46e5fb00-bea1-11e9-836d-be1b1c7d963f.png\")
\n ![](\"https://user-images.githubusercontent.com/586552/63046881-46e5fb00-bea1-11e9-87ee-80dbeb0bea1c.png\")
\n