Customizing Your Site
Customizing your site
This page describes some more advanced features of Pages and introduces Jekyll, one of the technologies behind Pages.
You may have realized that Pages is based on several technologies. One of the most important is Jekyll, a site generator. Pages uses Jekyll to build your site, so anything you can do with Jekyll, you can do with Pages. If you understand how Jekyll works, you can customize all aspects of your entire site.
The Pages templates are all configured to use a theme which houses all the HTML, CSS, and other web assets for your site. You can override everything on a per-file basis by including your own version of the file in your repo. Learn more about Jekyll themes.
Layouts and includes
Instead of complete HTML files, Jekyll uses the Liquid templating language to compile multiple layouts and includes. A layout is a container for your page that typically contains the most common elements across your pages, like the site header and footer. The layout is specified in the page’s front matter. Includes are HTML snippets or partials that allow you to reuse them across your site. A common include could be a UI component or a side navigation that is reused across the site. Learn more about Jekyll includes.
You can use CSS with Jekyll just like any other static asset. However, one of
Jekyll’s most powerful features is how it uses Sass to make writing CSS easier.
Sass files use the
scss file extension. Your main scss file should live under
assets/ directory. Learn more about Sass.
When you include an scss file under the assets/ directory, Jekyll will only
process it as Sass if you include the front matter marker (three dashes
Sass files under _sass/ can be imported by using the
@import syntax in your
main scss file. You can use this to organize individual UI component styles with
individual scss files, and then import them from an
U.S. Web Design System
The U.S. Web Design System (USWDS) is a design system for the federal government backed by user research to design and build fast, accessible, mobile-friendly government websites.
The USWDS is written in Sass, which is compiled by Jekyll to CSS. It is designed to be configurable, so you can make customizations by overriding variables or including additional CSS rules. Learn more about customizing the U.S. Web Design System.
The Pages themes are meant to keep things simpler for you, the site owner. To do this, the theme makes some assumptions on your behalf. Think of Pages themes as training wheels or guide rails. If you are making a lot of customizations and overrides, the theme might be more burdensome than it is helpful. That is okay! At this point, you probably want to remove the theme and take full control over your website by copying all the theme files into your repo and removing the theme from _config.yml and your Gemfile. This process is described in Jekyll’s documentation on converting to a regular theme.
Pages would also like to learn more about how the theme is or is not working for you. Please email us describing your experience so we can learn from you. Thank you!
Custom 404 pages
If a user navigates to a page on your site that does not exist, they will see a “404 Page” (webspeak for a page that doesn’t exist). Pages provides a default 404 Page (shown below), but you may prefer something that looks and feels like it is part of your site.
Pages default 404 page
In order to use a custom 404 Page, name your 404 Page “404.html” and make sure it is at the root of and included in the resources that are deployed. Jekyll sites should also have the file in the root of the project with the front matter data value set to
permalink: /404.html, see the docs for reference. If you need to direct 404 errors to a file not named “404.html” to support single page applications (SPA), let #cg-pages or firstname.lastname@example.org know that you would like to use a custom 404 page for a SPA and we will handle the rest.
If you have a custom domain and, while trying to set up your custom 404 page using a development branch, you are able to see it when running locally, but not live on the branch site, try pushing it to your custom domain.
Pages supports the proposed security.txt standard. Simply create and place the security.txt file within the .well-known directory created at the root of your repository. Visit the security.txt website, for more information on this proposed standard.