↖

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.

I created Neat CSS, the minimalist CSS framework.

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

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://codazoda.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

Grab the neat.html and neat.css files.

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

Create the default.html file

Create a _layouts directory and copy the neat.html file there with the following command.

cp neat.html _layouts/default.html

Edit the default.html file, delete everything inside the body, and add the content variable (in double curly braces).

Replace the title tag with the page.title variable (in double curly braces). Your default.html file should now look something like this.

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 site based on Neat CSS. To add a new page to the site simply 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.