Making A Jekyll Blog With Neocities
July 16, 2023 | Tags: personal programming
Hello there, this is my blog. It’s running on Neocities, a simple host for static HTML pages. It’s nice for beginners, as it lets you edit your HTML, JS, and CSS directly from the web interface, and see the results in real time. For many people, I’m sure this is a big improvement over something like GitHub pages, where you pretty much have to understand git in order to use it. (I am hosting this site on Neocities currently, but I’m also storing the code on GitHub for convenience.)
This blog post is going to give an overview of setting up a blog on Neocities, using Jekyll. This isn’t a tutorial, but instead is a basic overview of some of my setup.
Setting Up Our Environment #
While Neocities allows you to edit your page from the web, that’s obviously not ideal for making a complicated site (and definitely not feasible for making a Jekyll blog).
Luckily, Neocities provides a CLI we can use. It’s a ruby gem, so we can install it with gem install neocities. The important command for us is neocities push DIR, which will let us push a directory to our Neocities site.
We’ll also need the Jekyll CLI, which is also a ruby gem. We can install those with gem install jekyll bundler.
Tagging Posts #
Tags are useful on blog posts, because they let you see all posts organized around a certain topic. However, tags aren’t super useful out of the box. By default, Jekyll does not give an easy way to list posts by tag, or by date for that matter. Luckily, the Jekyll Archives plugin makes this pretty simple.
Jekyll Archives will automatically create a landing page for your certain categories. It can create pages for years, months, days, categories, and tags. For example, you can look at arnaught.neocities.org/blog/2023/07 to see all posts made in July 2023, or arnaught.neocities.org/blog/tagged/minecraft to see all posts tagged as minecraft.
Jekyll Archives is a little janky in some ways (It doesn’t give you any customization options for titles, and does not generate a title for date archives at all), but it was very simple to set up.
Uploading to Neocities #
When you build and modify your Jekyll site with jekyll build, the resulting site will be in _site/. You can push this directly to Neocities by running neocities push _site/, and your local Jekyll site will be uploaded and deployed on Neocities immediately! Now, there is a slight pitfall with this. Pushing won’t delete any files. So, say you make a blog post on your site, and you push it. Then you delete that post locally and push again. That post is still going to be on Neocities! Pushing will upload new and modified content, but will not delete anything.
To solve this, I ended up making a simple shell script to manage this. This script compares the local files in _site/ to the files on Neocities (which we can grab with neocities list -a). If it finds any files which exist on Neocities that don’t exist locally, it deletes those files on Neocitites. This way, if you delete anything locally, you can also easily delete it remotely!