Skip to content

How to write new pages

Jump to bottom
Jared C Cunha edited this page Jul 15, 2019 · 4 revisions

The design system documentation site uses Markdown. If you've never written with Markdown, the Markdown cheatsheet is a good place to start.

If you do not feel comfortable writing the content on your own, you can open a new issue, and the Formation team will work with you.

To write a page in any section, go to that section in GitHub and create a new file. Choose a file name wisely, because the file name will appear at the end of the page URL. The exception to this rule is for overview pages, where the file name is index.md.

The file extension must end with .md.

Every page requires the content between the two sets of ---. This section is called Front Matter.

You can copy this template to paste into your new page:

Note: In each of the examples below, you'll need to remove the square brackets entirely. The square brackets are placeholders for the content you will need to write.

---
# Do NOT Edit layout
layout: default

#Page info: Edit these items below
title: [Page title]
tags: [Write comma-separated list]
---

# [Main page title]

[YOUR CONTENT]

Let's break down what you can edit:

  • title: This is the text that appears in the left-hand navigation and the browser tab. Use sentence casing.
  • # [Main page title]: This will be the h1 on the page. This is often the same as the title, but it can be different if necessary. Use sentence casing.
  • [YOUR CONTENT] This is the rest of your post.
  • tags (optional): The site search queries words in the page title and URL, but sometimes that might be sufficient. Tags are used to provide additional keywords for the site search. If you do not need to use additional keywords, you may delete the entire line tags: [Write comma-separated list]. **When adding tags, be aware that they could potentially downplay how other, possibly more relevant pages, are indexed.

Note: When you are writing content in these templates, overwrite all the placeholder text including the square brackets

Where pages appear in the left navigation.

Pages will be sorted alphabetically by their file name in the left rail.

Changing the order of the left rail

If you need a page to be higher up in the left rail, for example, in the content style guide where the word list appears just underneath the overview, you can change the file name from word-list.md to 00_word-list.md. However, there is one small change you will need to make in the snippet above to the text between the two sets of 3 hyphens (---). You will need to add a slug field. The slug will help ensure that the 00_ does not appear in the URL.

---
# Do NOT Edit layout
layout: default

#Page info: Edit these items below
title: [Page title]
slug: word-list
---

# [Main page title]

[YOUR CONTENT]

Adding jump links to the left navigation

You can add anchor links to large pages to help users get to the content or see what is inside a section. Unfortunately, this is currently a manual process. The text of the anchor MUST match the text of the corresponding heading. You can have as many headings on the page as you like. As a general rule, it is a best practice to only use anchors for level-2 headings.

---
# Do NOT Edit layout
layout: default

#Page info: Edit this
title: [Page title]
tags: [Write comma-separated list]
anchors:
  - anchor: Anchor number 1
  - anchor: Another anchor
---

# [Main page title]

[YOUR CONTENT]

## Anchor number 1

[MORE CONTENT]

## Another anchor 

[MORE CONTENT]

Submitting your new page

Submit your new page as a pull request. The Formation team will respond as soon as possible.

Clone this wiki locally