Go back

Writing an article

To write a new article:

  • Create a new file in a subdirectory of the /src folder.
    Read about our information architecture to decide which subdirectory to use.
    Name the file with a .md file extension.

    e.g. my-article.md

  • Add this standard snippet of frontmatter at the top

---
layout: article
title: "Your title here"
description: "Your description here"
status: DRAFT
tags: your-tag-here
order: numeric-order
---
## First article heading

  • Leave the layout value as article.

  • Update the title and description values as required.

  • The article should be set at DRAFT status until you are ready to REVIEW or publish as FINAL.

  • The tags and order frontmatter control where the article appears in the site. This is covered below.

  • Write your content

Document control

You can declare status, issue sheet and document review information in the frontmatter data.

See the document control article for details.

Content

Content should come after the last --- in the front matter and use Markdown syntax.

Content is usually written in plain text using Markdown to apply a standardised formatting for things like headings and hyperlinks. Markdown files use a file extension of .md.

You can link to other articles by using the Markdown links syntax in your content. You should omit the .md extension and use ../ syntax to go up a directory: So if linking to an article my-article.md in the same directory, you should use this link syntax:

[My article](../my-article)

You can also display a group of related articles, by adding a ‘related’ attribute to your front matter:

related:
  title: Related articles
  tag: another-tag

In this example, we will display all articles that have the tag, another-tag. If you look at the bottom of the how to contribute article, you can see how related articles appear.

Using tags and order

  • Tags
    The tags attribute should be defined if you want the file to appear in ‘related’ articles. For articles to appear on the homepage, use home.

  • Order
    The numeric order attribute should be defined to control where this article appears amongst others with the same tag… Low values come first.

  • Multiple tags
    You can define multiple tags using this syntax so that the file appears in multiple collections.

tags: [home, dev]

Sometimes you may want to apply a different order in the different collections however. In this case you should use this syntax:

order:
    home: 1
    dev: 100

Tips

Adopt clear file names

Directory and File names are reflected in the final URL in the playbook so choose something that will read well.

Use all lower case with dashes to separate words.

Use directories to organise the articles

Directories aren’t specifically needed, but they make it easier for playbook authors to organise the information.

Use headings to structure content

Headings will display in the navigable table of contents and can be bookmarked by our users.

References

Improve the playbook

If you spot anything factually incorrect with this page or have ideas for improvement, please share your suggestions.

Before you start, you will need a GitHub account. Github is an open forum where we collect feedback.

Suggest a change to this page

Published: