View on GitHub

The Least You Need to Know About GitHub Pages

The least you need to know about GitHub Pages is laser-focused on one thing: showing how to get a working informational website up and running as fast as possible using GitHub Pages, using only the GitHub website.

Adding an assets directory to GitHub Pages

GitHub Pages is based on Jekyll, which expects graphic images and custom CSS to be in a directory named assets.

While you can store any kind of file in a GitHub directory, certain files get better treatment than others. If you want image files in your repo to display, or to customize the CSS, the easiest way is to follow Jekyll conventions and create an assets directory. Here’s how to do it in GitHub Pages. The assets directory should contain subdirectories for CSS and images.

Create the directory /docs/assets/css

Creating an assets directory is a two-step process because Git doesn’t recognize empty directories. You will therefore need to create the assets directory and add at least an empty style sheet (or any other file) at the same time.

Jekyll prefers the assets directory is directly under the /docs directory. So:

Notice that each type you type a slash, the GitHub editor creates a new subdirectory. That’s just what you want to happen.

Creating the style.scss file

Now it’s time to add text to the empty file.

---
---
@import "jekyll-theme-slate";

You’ve just created a minimal SASS file.

Jekyll, CSS, SASS, and SCSS files

CSS is a bit limited regarding variables, namespace scoping, and expression evaluation. Jekyll uses a preprocessor named SASS as its default style sheet formatting system. SASS files end in .scss, and by tradition the main such file is named style.scss. Part of the build process of converting a Jekyll site to the published HTML is reading the .scss file, then translating it into CSS.

Image files

You can put image files anywhere in the assets directory. Jekyll prefers them in assets/images but this publication simply puts them in assets itself.

Previous page Next page

Home