Home - TIL - Zines

Hosting Markdown on GitHub with Neat CSS

This page is a relatively rough draft. All the instructions are here but I haven’t fleshed out the wording. There’s some overlap with my previous article, Using Neat CSS on GitHub Pages, which I forgot I already put into words. I’ll probably update these instructions over time and merge the two documents but I wanted to get this one out right now. It’s also similar to How I Use GitHub as My Blogging Platform.

You can put a set of markdown files on GitHub and it will build them into a static website automatically.

You can use the Neat CSS framework to style those.

Here’s an overview of the steps.

Create a new repo on GitHub
Create a local directory for your code
Add an index.md file and push your code
Enable GitHub Pages for the repo
Download the Neat CSS files
Create the template (default.html) file

Create a new repo on GitHub

I do this through the GitHub UI. The repo starts out blank or with just a readme.

Create a directory for your code

Create a local directory for your code. Use something like ~/sandbox/hello-world.

Create an index.md file

Give it a title and a body.

# Home Page

Some _text_ goes here...

Commit it and push this code to GitHub using their instructions. Here are the commands.

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin git@github.com:codazoda/hello-world.git
git push -u origin main

You should now have a repo with just an index.md file.

Enable GitHub Pages for the repo

Settings, Pages.

Set main as the branch to deploy with / (root) as the directory and Save that change.

In a couple minutes this page will say your site is live at something like https://example.github.io/hello-world/.

Take a look at that URL. Your site is already built and live but it is using the default GitHub theme and domain name. We’ll change both of those soon.

Download the Neat CSS files

We’ll grab a tiny CSS file to style the web page. Grab the neat.css file with the following command.

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

Create the default.html file

Create a _layouts directory.

Add a default.html file and put the following simple html into it.

Note that the curly braces below are not doubled and they need to be doubled in order for them to work as variables.

<!DOCTYPE html>

<head>

    <title>{ page.title }</title>

    <link rel="stylesheet" type="text/css" href="neat.css">
    <link rel="stylesheet" type="text/css" href="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 }

</body>

</html>

Preview the website

That’s it, you should now have a basic static site. To add a new page to the site create a new markdown file in the root directory.

Linking

If you have a file called some-page.md you can link to that with the following markdown code.

[Some Page](some-page.md)

The .md file extension is optional so I ommit it.

[Some Page](some-page.md)

Indexing

The index won’t be built automatically. You’ll need to create a link to each of the pages in the markdown content of your index.md file.

Written by Joel Dare on June 29, 2024 and last updated March 31, 2025.

Do you have a question? I want to hear from you!

Ask Me Anything

Terms - Privacy