When constructing asset names (page names, file names, block names; previously system names), please adhere to the following best practices:
- Keep asset names short, using 1-3 relevant keywords
- Use only lowercase letters
- Separate keywords with hyphens
- Use numbers sparingly
- Do not use spaces or underscores
Where Do Asset Names Appear?
The Page Name of a page is the name that appears online at the end of the URL (.html will be automatically appended during publishing). It is also the name that is displayed in the navigation panel in Cascade.
For example: The URL for a page with the page name “about” will be www.brandeis.edu/your-site/about.html
The File Name of a non-page asset — such as an image or PDF — will not be as visible to someone visiting your site, but a descriptive file name still important for search engine optimization (SEO). It is also helpful to you as a web editor.
Scannable Asset Names
Consider these two possible asset names. Which makes it easier to guess the content of the photo without clicking on it?
If you have an images folder with 30 images within it, a descriptive file name like commencement-speaker-richardson.jpg allows you to scan the contents of the folder and find what you’re looking for faster.
Examples of Correct and Incorrect Asset Names
Numbers in Asset Names
Let's say you are creating a new page for an event, or uploading a new version of an application. Should you use the year in the Page Name or File Name?
In most cases, no. A year is usually not necessary and can even cause problems in the future. If you are updating a page annually, you wouldn't want to have to change the Page Name every year. And if you upload the application every year, you can overwrite the file rather than creating a new asset (but you don't want the year to be incorrect!). Aside from being more work for you, renaming the page will break any links from other websites to your site, and uploading a new file means you have to update every page where the old file was linked. So whenever possible, avoid creating asset names that are too specific.
- Commencement happens every year. The asset name for the Commencement Website is www.brandeis.edu/commencement not www.brandeis.edu/commencement-2017
- Perhaps there is a PDF of an application that needs to be updated every year on your site. Let's call the form application-major.pdf. If the form needs to be updated, you should replace that application-major.pdf file rather than upload a new pdf with a new name, like application-major-2017.pdf. If you don't replace/update the old file, it will still be indexed by search engines and can be found by potential applicants.