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.
I do this through the GitHub UI. The repo starts out blank or with just a readme.
Create a local directory for your code. Use something like ~/sandbox/hello-world
.
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.
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.
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 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="/">↖</a>
{ content }
</body>
</html>
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.
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)
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.