Finding, editing, and adding content

Plain text content

Unlike many websites, this site doesn't have a conventional content management system; instead, it's built with a static-site generator. There are advantages and disadvantages to this approach. On the one hand, static-site generation is simpler and more secure, with fewer moving parts (for one, it doesn't have a database). On the other hand, content is in plain-text files (usually in markdown format), and can be difficult to find if you're not used to this type of codebase.

Finding content

It's important to know where content lives in the file system, but if you just need to make a quick page edit, there's a cheat!

The cheat 😏

Let's say you want to make a change on an existing page, for example How GSA SmartPay® Works. You can select a line of text from that page (try to use text unique to that page).

In this example, I copied the text Agencies/organizations issue a task order.

I can then use the GitHub search with that text (wrapped in quotes) to find the file that contains it.

❗ When you search, make sure to wrap the text in quotes and select Search in this repository.

If you selected Search in this repository, you should get a result with the content file you're looking for, which you can then click on to go directly to that content file.

So you have that option! But if you need to make more significant changes, you'll want to know how the content is organized and structured.

Content structure

When you go to the main GitHub repository, you'll see a series of files and directories (folders).

Most of these files and folders are used for the code and configuration of the website, but one folder houses just about everything you'll need to edit and add content on the website.

The src folder

The src folder contains all of the content on the site (with the exception of public, which we'll come back to later).

When you select the src folder, you'll see yet more folders! One of those folders is the helpfully titled content folder. You can probably guess where this is going!

The content folder

Almost everything you need to edit is in this folder, and almost everything is in markdown format.

❗️You'll notice two types of markdown files in the content subdirectories: .md and .mdx. These are both markdown file formats, and are identical in most ways. The only difference is that .mdx can use astro components in the markdown. If a content file is in .mdx format, it probably uses a component. We'll cover components later on.

As of the time of writing, the content directory has 14 subfolders:

📁 content

• 📁 about
• 📁 audits
• 📁 contact
• 📁 faq
• 📁 how-it-works
• 📁 merchants
• 📁 nav
• 📁 policies-and-audits
• 📁 publications
• 📁 resources
• 📁 smartbulletins
• 📁 smarttax
• 📁 stakeholders
• 📁 state-taxes

This content structure mostly resembles the navigation structure presented to users on the website. Consequently, if you open the about folder, you'll see the content files in that section of the website.

📁 content

• 📁 about
  • 📄 benefits.md
  • 📄 business-lines.mdx
  • 📄 index.md
  • 📄 logos.mdx
  • 📄 master-contract.md
  • 📄 refunds.md
  • 📄 statistics.md
  • 📄 strategic-payment-solutions.md

So if you want to edit a line of text on the Business Lines page, you found the right place! Click on the filename to get to the page content!

❗ Any file called index.md is ✨special✨. Basically a file with the name index is the landing page for that section. So in the about section, the page will be at smartpay.gsa.gov/about, while Business Lines will be at smartpay.gsa.gov/about/business-lines

The other folders...

You may have noticed there are more folders here than sections of the website. That's because some folders have content that supports other content (e.g. state-taxes contains individual state tax pages), while another—nav—contains a file that drives the website's navigation.

❗ We won't cover this here in detail, but markdown files aren't sufficient by themselves to create pages on the website. The markdown files need an astro page to go into. The pages folder is located in the src directory, and each page basically pulls in the markdown content and presents it as a webpage. You'll only need to worry about pages if you create an entirely new section of the website. If you create a new page in an existing section (e.g. how-it-works), the markdown page will automatically become a page on the site. Pages are more complicated than markdown files, and you may want to consult an engineer to build or modify a page.

Editing content

Now that you know how to find content, here's how you make changes!

The anatomy of a content file

As mentioned, most of the content on the site is in markdown format. Markdown is a simplified version of HTML. If you need a markdown refresher, you can always check out the GitHub markdown cheatsheet!

Markdown files are pretty straight forward, but because some pages are built differently than others, the format might change slightly from file to file.

Front matter

Markdown files begin with "front matter". Front matter is essentially content metadata. It can also contain elements that might need specific styling or formatting, or content that is used in other places (such as the meta description, which is used by search engines).

Front matter looks like this:

---
title: Business Lines
description: "GSA SmartPay business lines include purchase, travel, fleet, tax advantage, and integrated."
intro: "There are several business lines associated with the GSA SmartPay® program."
order: 2
category: about
tags:
  - account
  - purchase
  - travel
  - fleet
  - tax advantage
  - integrated
---

This format is called YAML, and you'll see it elsewhere in the codebase. It uses key:value pairs to define variables that can be used in various ways.

Here's what they do:

Key	Description
title	used to create the heading 1 on the webpage (and the title tag in the page's metadata)
description	used to populate the page's meta tag for search engine optimization
intro	used for the opening paragraph on some pages, which is slightly larger and a different color than the rest of the text
order	controls the order of the page in the side navigation
category	the 'group' the content belongs to — not currently used (but could be)
tags	used for taxonomy to tag related content — not currently used (but could be)

You'll notice that neither category nor tags are currently used for any site functionality. We added these so that you could use them if you wanted to. They can be used to show all content with certain tags. For example, you could use them to build a page that shows all content tagged with travel (regardless of where the content "lives" on the site). Or you could use them to filter audits by agency (since each audit has a tag indicating the agency to which the audit applies). Again, you don't have to worry about these right now, but if you add new pages, I suggest adding them, just so you have the option to use them down the road.

❗ Technically, you can publish a page without front matter, but it would be a mess. Without a title, it won't show up in navigation, and it won't have an page title (h1), which will result in accessibility errors. If you want to publish a new page, it needs to have front matter for the site to work properly!

Pages with different front matter

While most pages will have the front matter you see above ☝️, some pages have different front matter. The most complex version of this is state taxes.

In order for state tax pages to use the same layout and structure, much of the variability of the content and design elements is driven by the front matter. Here's an example:

---
name: Arizona
contact:
  link: https://azdor.gov/
  name: Arizona Department of Revenue
  phone: 602-255-3381
summary:
- icon: highlight_off
  text: Individually billed accounts (IBA) <b>are not</b> exempt from state use tax.
- icon: highlight_off
  text: IBAs <b>are not</b> exempt from transaction privilege tax.
- icon: check_circle_outline
  text: Centrally billed accounts (CBA) <b>are</b> exempt from state use tax.
- icon: error_outline
  text: CBAs <b>may not be</b> exempt from transaction privilege tax.
updated: 2023-02-15
---

Let's go through these by first looking at the rendered page elements.

Both of these sections are controlled by the front matter. The contact information is listed first in the front matter, so let's start there (even though the contact section is at the bottom of the page).

The page template looks for the contact information and places it on the page. So link, name, and phone from the front matter will populate under the contact section on the page. Pretty self explanatory!

Let's dig into the summary section. Basically, the page template for state tax information will populate this section if the summary key is present in the front matter. Since every state and territory page has content for this section, this block will display on every tax page, so long as summary is present in the front matter. Here's an example from Arizona:

summary:
- icon: highlight_off
  text: Individually billed accounts (IBA) <b>are not</b> exempt from state use tax.
- icon: highlight_off
  text: IBAs <b>are not</b> exempt from transaction privilege tax.
- icon: check_circle_outline
  text: Centrally billed accounts (CBA) <b>are</b> exempt from state use tax.
- icon: error_outline
  text: CBAs <b>may not be</b> exempt from transaction privilege tax.

The summary is an "object", which basically just means it has other key:value pairs associated with it. Let's go through them.

Key	Description
icon	Picks the USWDS icon to associate with the text. The names here, while not always descriptive, are those used by USWDS.
text	The text that accompanies each icon

❗ Front matter is in YAML format, which is highly sensitive to spacing (indentation). If a line is indented two spaces, you must retain those two spaces for the website to build properly. If a line has a hyphen, you should retain that hyphen in your edit.

For the purposes of icon use on individual state tax pages, the website is designed to use three options (approximated here with emojis):

Icon style	icon name	Purpose
✅	check_circle_icon	Indicates tax exemption (doesn't require action from the user)
❌	highlight_off	Indicates an account is not exempt from a given tax
⚠️	error_outline	Indicates an account may not be exempt from a given tax, or the state has an additional tax or form

❗ Front matter often uses straight quotation marks ("") for programming purposes. Basically, the quotes are important for indicating text that should be treated as a "string" of text (instead of instructions or operators). This means quotations can be tricky in front matter. If a front matter entry has quotations around it already, it's safest to keep them there (even if you change the text in between the quotes). If you find the need to use quotation marks in the text of the front matter, straight quotes (the default on your keyboard) will cause problems, since the code can no longer tell the difference between the quotes it needs and the quotes you're using in the text. For this reason, it's best to use curly or so-called smart quotes (“”) if you need to use quotes in the text itself. Curly quotes have the added benefit of making the text easier to read.

The website will automatically convert straight quotes (and apostrophes) to curly counterparts in most areas of the website, but double quotes in the front matter is the one place that the site code won't be able to properly convert them. If you want to use double quotation marks in the front matter, use this key to create curly quotes instead of straight quotes:

Special character	Windows	Mac	HTML
Opening single quote (‘)	alt 0145	option + ]	‘
Closing single quote (’)	alt 0146	option, shift + ]	’
Opening double quotes (“)	alt 0147	option + [	“
Closing double quotes (”)	alt 0148	option, shift + [	”

So for example, if you're on Windows and want to place opening double quotes, hold down alt while typing 0147 to generate “.

Date format

You'll notice the date format in the front matter is different that what ends up on the rendered webpage. For example, the front matter for Arizona above has the updated key with the date formatted as 2023-02-15. The code for the site will automatically reformat the date and display it at the bottom of each state tax page. In the case of Arizona, it displays as “Updated February 15, 2023”. While this reformatting happens automatically for you, the website code expects a specific format in the front matter for it to work properly, so use the year-month-day format when you update the, er, updated date!

Images and documents

You'll need to add or replace images and documents at some point. Images are slightly more complicated in this tech stack than are PDFs (for example), but we'll cover both here.

❗ Remember that images are inherently visual, and consequently are difficult to make accessible for all users. Use discretion when deciding to use images, and try not to use images for decorative purposes only. Always write descriptive alt text that describes the visual characteristics of the image as if you were describing the image to someone over the phone (someone who can't see it). Likewise, PDFs don't display well on phones and are inherently less accessible (because they don't have a predictable content structure; don't display well on all devices; and are usually larger in size than a webpage with the same content).

Images

Most of the images you add will be placed in the public folder. That folder is at the root level, which just means you don't need to open another folder to get to it. If you want to add or change an image on the site, this will (almost always) be your go-to place.

Under public, you'll find a folder called images.

• 📁 public
  • 📁 images

❗ The 📁 public folder is basically a "pass-through", which just means there's no special processing that needs to happen to the contents. For example, content in markdown format in the src folder needs to be processed and turned into HTML (among other things) before it can be a viable webpage, but images and files in the public folder don't need any special processing to work in the browser.

Once you add an image to the images folder, look at the existing code to figure out how to place that image in the relevant page. Depending on the page, it will look something like:

HTML page <img src="/images/gsa-smartpay-logo_thumb.svg" alt="GSA SmartPay Logo with GSA star logo, SmartPay, and Supporting your mission" />

or

Markdown page

![Silver charge card with the words Tax advantage and numbers 1234 5678 9012 3456 and the name John Smith, with a car and buildings in the background](/images/silver-card.png)

Some images require processing, either because they're part of a component or for other programmatic reasons. Those images need to be imported into the page or component, and the syntax for that looks like this:

import gsa_logo from '@assets/images/gsa-logo.svg'

Because those images need to be processed, imported, or otherwise programmatically influenced, they are stored in a different location:

• 📁 src
  • 📁 assets
    • 📁 images

You probably won't need to add many photos in this location (and they'll be more complicated to use if you do), but you might need to replace an image in this location. So there it is!

Documents

Documents (like PDFs) are similar to images, except all of them will be in the public folder. If you need to add or replace a PDF or other document, you'll find it in the files directory:

• 📁 public
  • 📁 files

There's additional organization in this folder, which helps both you (as content manager) and the user (because, for example, audits will publish to a URL path that confirms they are, in fact, audits: /files/audits/2020-hud-travel.pdf)

• 📁 public
  • 📁 files
    • 📁 audits
    • 📁 policies
    • 📁 publications
    • 📁 smartbulletins

Try to keep your files and folders organized! It will help you find, update, and remove files down the road!

Because some PDFs are linked from button-styled elements, they require a component to furnish the link. It will look something like this:

<LinkButton link="files/audits/2020-sec-travel.pdf" text="View full audit [PDF, 50 pages]" />

In markdown, you'll be able to use a slightly simpler syntax:

[Chip and PIN/Signature Cards [PDF, 2 pages]](/files/publications/publications-chip-pin-signature-cards.pdf)

❗ Try to use a consistent format for file names. Starting with a year, for example, helps organize the files in the repository, making them easier to find and more intuitive for users. Avoid spaces in your file names, and try to only keep the most recent and relevant version of the document (replace and old version with a new version instead of keeping both, if you can). Come up with a simple naming format for the team that works for you and for users, or adopt the filename format we've used so far.

Conclusion

You're doing a great job! Congratulations for making it this far! 🎉 🍾

We understand that there's a lot going on here, but it's not as complicated as it might seem. As mentioned, this codebase is actually less complex than what many teams are used to working with, but you're exposed to more of the underlying code than when using a conventional content management system. Thankfully, it's rather difficult to break anything on the website itself! The workflow via GitHub is set up to allow you to make changes without unintentionally breaking something on the production website.

One of the benefits of working this close to the code is that you're encouraged to think about your content structure, organization, metadata, and other aspects of your content that are often overlooked when working with a WYSIWYG ("What you see is what you get") editor in a content management system. Working with your content in markdown encourages editors to think about heading structure, descriptive link text, alt text, and other important considerations for accessibility, among other things.

Because GitHub keeps a record of every change to the website, you don't need to worry as much about keeping track of the changes you made (for the purposes of FOIA, etc.). GitHub will track all of your changes, making it relatively easy to revert back to a previous version. Your repository is open to the public, so interested people can track the changes you're making, and even add issues or pull requests to help improve the website! And because most of your content is in markdown now, you can more easily migrate it to a different codebase in the future, if you choose to.

Well done on building a more accessible, streamlined, and user-friendly website! 👏 And remember, the GSA Service Delivery team is here to help you if you ever get stuck!