Joel Dare

Using Neat CSS on GitHub Pages

Create a GitHub Pages site with nothing but markdown files and make it look great with Neat CSS as a template for your pages. Neat CSS is a minimalist CSS framework.

Jekyll is built-in to GitHub Pages so you don’t need a build step—the markdown files will be processed automatically. You can also read more about How I Use GitHub as my Blogging Platform.

Overview

Create a _layouts directory
Copy and paste the default.html file
Add an assets directory
Add an assets/neat.css file
Add an assets/custom.css file

Layouts

The layouts directory goes in the root if you’re serving GitHub Pages from the root of a branch. If you’re serving from the docs directory then it goes in docs/_layouts.

default.html

Here’s an example of the default.html file that goes in the _layouts directory. You can use this as-is or you can tweak it to your own taste.

<!DOCTYPE html>

<head>

    <title>{ page.title }</title> <!-- Double Curly Braces Here -->

    <link rel="stylesheet" type="text/css" href="assets/neat.css">
    <link rel="stylesheet" type="text/css" href="assets/custom.css">

    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta charset="UTF-8">

</head>

<body>

    <a class="home" href="/">&nwarr;</a>

    { content } <!-- Double Curly Braces Here -->

</body>

</html>

neat.css

You can download the neat.css file with the following curl command.

curl -O https://neat.joeldare.com/neat.css

custom.css

Create a custom.css file to put any custom CSS in. This way you can update the neat.css file, in the future, without blowing up your custom changes. The following command will create a blank file for you.

touch custom.css

Written by Joel Dare on March 19, 2024 and updated on April 15, 2024.