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.

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

# 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

Enable GitHub Pages for the repo

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

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.

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.

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.