URLs and Filenames

A good URL is:

• Short
• Easy to remember
• Easy to type
• Well-organized

Even if you can’t control the whole URL, use the parts you can to make it better.

Every page on your site should have its own unique URL so users can bookmark or share it.

• Use hyphens to separate words (this is called kebab case).
• Leave out small words like a, an, and the.
• Use the base form of verbs (like /make-thing/ instead of /making-thing/).
• Avoid extra or unnecessary words.

• Domains should be short and user-friendly.
• Don’t include deep department names unless they matter to users.
• You don’t need “www.” at the beginning.
• Use lowercase letters only.
• Use abbreviations if users will understand them.

Example improvements:

• www.longnamecreationservice.departmentoflongnames.bureauofnames.gov
  → make-long-names.bureauofnames.gov
  → bureauofnames.gov/make-long-names

Paths are the parts after the domain, like /content-guide/urls-and-filenames/.

• Keep them short, but it’s okay if they’re longer than the domain.
• Use hyphens to separate words.
• Use lowercase only.
• Avoid showing file types like .php or .html.
• Make sure users can remove part of the path and still find useful content.

Example improvements:

• /services/default/php/forms/longnamecreationservice/index.php?action=create
  → /make-long-names/

People bookmark and share links, so it’s important that URLs don’t break.

• Try to keep original URLs working.
• If you change a URL, set up a redirect from the old one to the new one.
• Plan ahead to make URLs last a long time.

Good filenames are:

• Lowercase
• Use hyphens instead of spaces
• Descriptive but not too long
• Easy to understand

Examples:

• Correct: summary-of-pay-gap-findings.pdf
• Not the best way: smmrypgpfnds.pdf

If the file is tied to a date, include it in this format: YYYY-MM-DD.

Examples:

• pay-gap-report-2024.pdf
• newsletter-2025-08.pdf

Avoid special characters (like #, &, %) and don’t use spaces.

URLs

• Always write URLs in lowercase, even if they start a sentence.
• Paths (the part after the domain) are case-sensitive, so keep their original capitalization.

On Web Pages (Interactive)

• Make URLs clickable links.

• Don’t include the beginning part like https:// in the link text.

  Correct: Visit gsa.gov for more information.
  Not the best way: Visit https://gsa.gov for more information.

In Print or Non-Clickable Text

• You can leave out http:// or https:// if both work.
• If the URL is long or awkward, put it in angle brackets:
  <https://example.com/this-is-a-long-url&gt;

This is especially helpful in emails, where the email program might not turn the URL into a link.

• Filenames are case-sensitive. Keep the original capitalization.
• If a filename starts with a lowercase letter, don’t capitalize it—even at the beginning of a sentence.
• You can also use angle brackets for filenames if needed:
  <summary-of-pay-gap-findings.pdf>

A full URL might look like this:
https://pages.bia.gov/content-guide/specific-words-and-phrases/#main

Here’s what each part means:

1. Protocol – https:// (use this unless you must use http://)
2. Domain – pages.bia.gov (the main site)
3. Path – /content-guide/specific-words-and-phrases/ (the page location)
4. Query string – ?q=18f+content+guide (optional, usually for searches)
5. Fragment – #main (optional, jumps to a section on the page)

Avoid using query strings and ports in URLs when possible. Fragments are okay if they help users, but don’t rely on them to find content.

Screen reader users often skip from link to link, so link text should make sense on its own.

Don't Use:

• Click here
• Learn more
• Here

Use instead:

• See the IA Code of Conduct for more information.
• Download the 2025 Pay Gap Report.

This also helps with search engine results and makes your content easier to scan.