Skip to content
This repository has been archived by the owner on May 9, 2023. It is now read-only.

Content management in cv_faq

Jump to bottom
Jona Decker edited this page Aug 3, 2020 · 56 revisions

Thank you for contributing content to faq.coronavirus.gov. This is a guide to content management for the site.

Contents

Introduction

Our site is built in Jekyll, a static site generator. The codebase is stored and managed in GitHub, and the site is published with Federalist.

Structure

As a content manager for this site, you'll need to know where the content-related files are stored.

Content files

Most of the content you will need to manage is stored in the _content directory (folder). Here are some general characteristics of the content files:

Front matter

Each content file must have front matter for the site to work properly. Here's an example:

---
date: March 20, 2020
excerpt: Keeping your home safe
layout: post
promoted: false
sources:
- agency: cdc
  url: https://www.cdc.gov/coronavirus/2019-ncov/faq.html#anchor_1584388242595
title: What steps can my family take to reduce our risk of getting COVID-19?
---

Characteristics of front matter:

  • yaml format
  • must have three hyphens at beginning and end
  • formatted as key/value pairs (key: value)

Here's how the front matter in content files works:

  • date: The date that will appear as "Last updated" for each question.
  • excerpt: A field for entering concise descriptions of the content (we don't use this at the time of this writing)
  • layout: Selects the layout for this content (as a content manager, you'll probably never change this).
  • promoted: If set to true, this will move the content up the list of questions in each category. If only one markdown file is set to true, it will appear at the top of the list on its category page. If several files are set to true, they will sort alphabetically above those set to false. If none are set to true, the order will be alphabetical.
  • sources: Lists the government agency content "owner" or "owners" and webpage. See Multiple sources for more information..
    • agency: Government agency that "owns" the content (agency must be preceded by a hyphen -). This must match the corresponding agency name in the agency's markdown file located in _agencies (more on agencies below).
    • url: Government agency webpage with the source content.
  • title: The title, formatted as a question, that appears in the accordion on the site
  • redirect_from: An optional field for entering the path and URI for an outdated FAQ which should be redirected by the server to this more authoritative FAQ instead:
    • redirect_from: /financial-help/the-irs-does-not-have-my-direct-deposit-information/
    • Note: Any file that is being redirected to a new, more authoritative FAQ should be deleted from the code repository. See Multiple redirects for information about more involved lists of redirects.
Multiple redirects

Some content may have a number of FAQs that need to be deleted and redirected to a new, more authoritative FAQ. Here's the format when there are more than one redirect to an FAQ:

redirect_from:
- /financial-help/is-the-government-delaying-tax-day/
- /financial-help/unable-to-file-taxes-by-july-15/
- /financial-help/already-filed-extension-but-have-not-paid-taxes/
- /financial-help/expect-to-file-taxes-by-july-15/
- /financial-help/how-can-i-file-the-tax-return-needed-to-receive-payment/
Multiple sources

Some content files have two sources. Here's the format when there are two sources:

sources:
- agency: treasury
  url: https://home.treasury.gov/news/press-releases/sm953
- agency: irs
  url: https://www.irs.gov/coronavirus

Adding a new content file

The easiest way to add a new content file is probably to copy an existing one, rename it, and edit the front matter. Then write or paste your content below the front matter (below the second ---). Format the content in markdown (or HTML, if required). Make sure there's an .md extension on the file name.

Add the new file to the appropriate category directory. If it's a new category, you'll need to add a directory for the category and move the file into the category directory. It's good practice to name your category directory with the same name as the category itself (more on that 👇). You'll also need to create a markdown file for the category in the _categories directory.

Deleting content files

When FAQs are deprecated by the content partner, the files should be deleted from the repository. In some cases, the content partner may also provide a replacement FAQ that the URL for the deprecated content should be redirected to. See the Front matter redirect_from section of the Wiki for more information on redirecting FAQs that are being deleted. In other cases, the content partner may ask for a deprecated FAQ to simply be deleted. If inbound external traffic to the URL is sufficient, it may be prudent to redirect that URL to either the category landing page, or the FAQ home page. If there's no sensible redirect target for an FAQ being deleted, it can be allowed to 404. Regardless of whether content is being redirected or allowed to 404, when FAQs are deleted, there are a few additional steps to take to ensure a clean, user friendly experience:

  1. Request that the page be de-listed in Search.gov
  2. De-list the page in Google Search Console

Categories

Content is arranged into categories. Categories are referenced in the front matter of the content files (see 👆), but they also have their own markdown files. Every category must have a markdown file. Category markdown files are located in the _categories directory.

Front matter

Each category file must have front matter, and category files only have front matter (no content outside front matter). Here's an example:

---
layout: category
name: rumors
title: "Rumor control"
owner: FEMA
banner:
  display: false
  heading: "This is a place to place urgent information"
  content: "You can set this component to 'display: true' to show a banner at the top of the page."
---

Here's how the front matter in category files works:

  • layout: Selects the layout for categories (as a content manager, you'll probably never change this).
  • name: The category name that links category markdown files to content markdown files. The name in content markdown files for each category must match what's entered here for that category. The format should be lowercase, with multiple words separated by hyphens (computers appreciate this sort of thing). Here's another example: parents-and-children.
  • title: The title of the category. This is what will show up on the webpage.
  • owner: A place to enter the "owner" of the content for this category, probably a government agency.
  • banner: An alert banner that will show up on the category page, styled in yellow with an icon above the main content.
    • display: Set to true or false. The banner will show up on the page when set to true.
    • heading: Heading text, styled as a heading level 3 (<h3>)
    • content: This is content of alert that will show up under the alert heading.
  • questions: The list of questions that should appear on this category page, in order. The name in the content markdown files for each question must match what's entered here for it to appear in this category, regardless of what content directory the file is located in. The format should be lowercase, with multiple words separated by hyphens, but without the .md file extension, for example:
  • who-is-at-higher-risk-for-serious-illness-from-covid-19

Multiple categories

Some content may fall into multiple categories. The "primary" category will always be the content category directory the FAQ resides within. But adding the filename (no path required) to the list of questions in any category will allow that FAQ to be listed on any category page, in the order that makes the most sense. That means that a question can be "promoted" (top three) in one category but not promoted in another category.

Agencies

In order to generate pages for each government agency that contributes content to the site, we maintain a markdown file for each agency in the _agencies directory. These files also map to the source front matter for content files.

If you receive content from a "new" agency, you'll need to add a markdown file for that agency. For instance, if you receive content from the Department of the Interior, you'll want to add an interior.md file with properly formatted front matter to the _agencies directory.

Front matter

Agency markdown files contain only front matter. It looks like this:

---
layout: agency
name: cdc
title: "CDC"
sitemap: false
---
  • layout: Selects the agency layout located in the _layouts directory
  • name: This is the unique "id" for the agency. For the site to work properly, agency references under source in content files must match the corresponding agency name here. For instance, if the source for a given content file is CDC, the agency front matter must list cdc (lower case).
  • title: The version of the agency name that actually appears on the rendered pages.
  • sitemap: Set to false, this key prevents these markdown pages from inclusion in the autogenerated sitemap.

Homepage "promoted" content

The homepage of the site includes a prominent search bar, and below it, "Top Questions" and "promoted questions". This content is stored in the _data directory, in the homepage_promotion.yml file. The format of this file is the same as the front matter in the files described above (yaml).

Top questions

Here's the current state of the top questions on the homepage:

top_questions:
  - icon: stethoscope
    link: >-
      /symptoms-and-testing/#what-are-the-symptoms-and-complications-that-covid-19-can-cause
    question: What are the symptoms?
  - icon: test
    link: "/symptoms-and-testing/#should-i-be-tested-for-covid-19"
    question: Should I get tested?
  - icon: globe
    link: /spread/how-does-the-virus-spread
    question: How does it spread?
  - icon: group
    link: "/keeping-home-safe/#how-can-my-family-and-i-prepare-for-covid-19"
    question: How can we prepare?
  - icon: chart
    link: "/keeping-home-safe/#what-steps-can-my-family-take-to-reduce-our-risk-of-getting-covid-19"
    question: How do I reduce my risk?
  - icon: plane
    link: /travel
    question: Can I travel?
  • Change the question text using the question key.
  • Change the link using link. This will be the file name without the .md extension and an opening forward slash (/).
  • The icon is a simple description of the SVG icon for each top question, but these map to icon files in the _assets directory. If you need to change an icon, you may want to work with an engineer to add an icon for it if one doesn't already exist.

Changing the order of these top questions in this file will change the order on the homepage.

Promotion boxes

Here is the current state of the promotional boxes:

questions_box_1:
  questions:
    - link: /protect-yourself/am-i-at-risk-for-covid-19-in-the-united-states
      question: Am I at risk?
    - link: >-
        https://www.cdc.gov/coronavirus/2019-ncov/prepare/managing-stress-anxiety.html
      question: How can I manage anxiety and stress?
  title: How to protect yourself
  view_all_link: /protect-yourself/
questions_box_2:
  questions:
    - link: >-
        /symptoms-and-testing/what-are-the-symptoms-and-complications-that-covid-19-can-cause
      question: What are the symptoms of COVID-19?
    - link: "/symptoms-and-testing/should-i-be-tested-for-covid-19"
      question: Should I get tested?
  title: What to do if you feel sick
  view_all_link: /symptoms-and-testing/

The two boxes are marked as question_box_1 and question_box_2.

  • Change the heading for each box by changing title.
  • Change the text for each question with question.
  • Change the link for each question with link, formatted as the file name (without .md extension) with a leading forward slash (/). Link to a category for the question with view_all_link (corresponds to View all >> link) at the bottom of each each box on the homepage.

Changing the order of the questions in this file will change the order in each box.

Indentation in yaml files is super important. Be sure to preserve the indentation in the file.

Homepage category order

A separate file in the _data directory determines the order of categories on the homepage. In that directory, you can change the order of categories in the homepage layout by adjusting the order in homepage_order.yml. The file looks like this:

categories:
  - name: symptoms-and-testing
  - name: spread
  - name: travel
  - name: keeping-home-safe
  - name: funerals
  - name: parents-and-children
  - name: medications
  - name: pregnancy
  - name: support-for-business
  - name: community-events
  - name: water-transmission
  - name: rumors
  - name: protect-yourself
  - name: underlying-conditions
  - name: animals
  - name: basics
  - name: financial-help

Again, mind indentation in your YAML file. :)

Also, if you add or remove a category, you'll need to add or remove it here. For instance, if you add a category for sports-venues, you'll need to add it here, and place it in the order in which you want it to appear on the homepage.

GitHub and Federalist

The site code and content is stored in GitHub. A full GitHub tutorial is beyond the scope of this documentation, but we'll cover some basics about our team's use of GitHub for this project.

You can learn the basics of using GitHub Desktop here.

If you don't have access to the cv_faq repository, you'll need to request access from a repository admin or in the TTS GitHub Slack channel.

Team changes are in the preview branch

GitHub uses branches to manage contributions from multiple team members. Effective 05-20-20, all content, code and design changes are staged in the preview branch. Once approved, those changes are merged into the master branch.

When you start working for the day, it's good practice to pull down ("fetch") any changes to the site since you last contributed. All team members from engineering, product, design, and content are contributing to the master branch, where everyone's work ends up.

It's good practice to try keep your branches as up to date with master as possible. This helps reduce merge conflicts. Merge conflicts happen when two or more people change the same part of the site and both try to merge. The older your branch gets, the more likely someone else on the team has changed something related to what you're working on.

Create a branch for your changes

Once you pull changes from the remote repository in GitHub, you can create a new branch for your work. Most of the time, you'll want to create your branch from the most recent version of preview. You can name the branch anything you want, but we generally use the naming convention of Agency-changes-date e.g., CDC-edits-adds-deletes-2020-05-15

Commit changes and push to remote repository

Once you've made your changes or contributions, you can "push" your changes to the remote repository. This just means that the changes you've made in your branch will be available to other team members on GitHub.

Open a pull request (PR)

For your changes to get into the pipeline for release to the website, you'll want to open a pull request. A pull request is a request to the team to merge your changes into the preview branch. When merged, your changes will be combined with the rest of the team's changes to the site.

When you open a pull request in GitHub, it's best to include the following:

  • Describe your changes or additions, including rationale or context.
  • Add a reviewer or reviewers to take a look at your changes.
  • If the changes correspond to a GitHub issue, include Fixes #100, filling in the issue number so reviewers can easily link back to it.
  • Make sure CircleCI tests pass (if CircleCI tests fail, you may want to work with an engineer to find out why)
  • Once Federalist finishes building your branch (more on this below), add a preview link so reviewers can preview your changes on a working version of the website. Ideally, you should include a direct preview link for any new or edited pages to make the reviewer's job easier
  • Don't merge your own pull requests! It's good practice to have someone else merge your pull request (usually one of the reviewers).

After the pull request is merged into preview:

  • Close the corresponding GitHub issue, if fully resolved by your changes.
  • Verify that your branch has been deleted in GitHub (this should happen automatically, based on our repository settings). You can always restore your branch, if needed.

Federalist

We use Federalist to build the website code and deploy the site. Federalist creates a preview for every branch pushed to the repository. You'll want to request access to the Federalist Site Admin in Slack, which will authenticate using your GitHub login credentials. With access to Federalist, you'll be able to track branch builds and errors, and you'll be able to access preview links.

Clone this wiki locally