Adding a Page

Table of contents

Step 1 - Create a page
Step 2 - Front matter
Step 3 - Adding to the nav
Step 4 - Authoring

Table of contents

Step 1 - Create a page
Step 2 - Front matter
Step 3 - Adding to the nav
Step 4 - Authoring

Step 1 - Create a page

Within the docs/content directory is where all the pages are stored. From docs/content/ the folder structure should match the desired URL. For this particular page, a recipe for adding pages, I wanted the URL to be something like documentation/recipes/adding-a-page. This meant I would need to add a directory with docs/content/documentation called recipes.

Step 2 - Front matter

Front Matter is information about the page you are authoring. There are four "variables" that are supported.

Title and description

title is used to render the page heading and generate the page title.

description is used to create a meta description tag which is important for SEO. These are required on every page

---
title: Adding a Page
description: Adding Documentation
---

Status

The status variable is provided by the doctocat theme and provides a label at the top of the page indicating the status of your subject.

---
status: New
---

Source

The source variable is provided by the doctocat theme and provides a link at the top of the page back to the source code of your subject.

---
source: https://github.com/xedi/sdk-js/blob/master/docs/content/documentation/recipes/adding-a-page.mdx
---

Additional contributors

At the bottom of each page is a list of people who have contributed to that page. From time to time, you may find yourself needing to use code or content from other authors. For example, you may choose to use fixtures written by another developer. In this situation, it's nice to recognise those contributions. You can do this by adding the additionalContributors variable.

---
additionalContributors:
  - midmiddlton
  - ehtishamSaleem
---

Step 3 - Adding to the nav

If you want your page to appear within the sites navigation, you will need to place an entry within the nav.yml file thats in docs/src/@primer/gatsby-theme-doctocat/.

Inside the file, find the where you want your page to appear in the listing (the nav is rendered in the order defined). You should provide a title and url. If you are defining a new section, then you should also provide a list of children.

- title: Recipe - Adding a Page
  url: documentation/recipes/adding-a-page

Adding a page

- title: Recipes
  url: documentation/recipes
  children:
    - title: Recipe - Adding a Page
      url: documentation/recipes/adding-a-page

Adding a new section

When defining a new section there are a couple of caveats to be aware of, and these are covered in the section about the Sidebar.

Step 4 - Authoring

Depending what you are writing about, how you write about it and the components you will use will differ.

API documentation is relatively simplistic compared to technical documentation. Here are some general guidelines.

Complete front-matter as completely as is necessary.

Document all issues and workarounds.

Provide links to all issues use the <GithubIssue> component.

Don't

Put sensitive information like keys, access tokens or passwords into documentation.

Use the <Flash> component to emphasis important sections.

Edit this page on GitHub

2 contributors

Last edited by samb20 on September 4, 2020