Writing YML

Most of the content on USDS.gov that isn't a people or project page is written using YML files inside the _content directory.

When writing YML, the most important thing is to make sure that you properly nest the content with key/value pairs. What is a key/value pair? In short, the key is the text on the left, followed by a colon, and the value is the text on the right. We'll be using the terms key and value on the rest of this page.

key: value

Before we proceed, so this does not scare you if you are not a developer, if you make a mistake in formatting YML on this site, you will not break it. The site will not build until you fix the error. If you are updating a YML page, check usds.gov regularly and check your email for build failure notifications. You should know if it worked within about five minutes.

General rules for keys

• Cannot use spaces
• separate words with underscores or hyphens
• Do not include any special characters
• You cannot have two matching keys at the same level.

General rules for values

• Usually a string of text
• Cannot include a colon without putting the whole line quotes

  this: is bad: no

  this: "is good: yes"

• You may include markdown if you use |-

  key: |-
     ## USDS
     The best of technology.
     The best of government.
     And we want you.

  • This is where nesting is very important. You must nest your markdown content on the level of indentation.

For more information about YML and how Jekyll works with it, read about Jekyll's data files