I recently uploaded the source code for NEOBLOG, a "minblog" template that makes it easy to feature a news feed on your static site. This is what I use for the "what's the latest" block on my main page.
This format actually caused quite an issue for me when I was first trying to upload it to neocities; YAML (YAML Ain't a Markup Language) was my language of choice for configuring and serializing the blog's data, and .yaml files weren't whitelisted by Neocities!
I ended up renewing my supporter account (I had stopped paying the subscription months ago while Out Of Money), then after the site was safely uploaded in time for Scump Sunday I sent an email to Neocities support. Well, everyone say thank you to Neocities staff, because now .yaml, .yml, and even .toml files are supported by Neocities! I'm kind of honored to be responsible for a tiny little chunk of this beautiful platform's functionality, but I'll try not to toot my own horn anymore about it -_-
Anyway, now that .yaml files work for free-tier Neocities users, I feel obliged to give a more in-depth tutorial for people looking to use it.
First, I'll go into some technical detail on how NEOBLOG works, then I'll give step-by-step instructions on how to make your own miniblog with it! I suggest skipping to the instructions if you aren't interested in knowing the internals :3
The goal of NEOBLOG is to improve the miniblogging experience. The way I used to miniblog was a travesty: I had a separate html file for for every single page in the blog (1.html, 2.html, etc...), on which I would copy-paste templates for each post, something like:
<div class="post">
<div class="post-header">
10/22/21 3 PM ET
</div>
<div class="post-content">
<p>Geez guys, this Coronavirus thing just won't go away!</p>
</div>
</div>
It made posting on there such a pain that I rarely did it, especially when a page had filled up and it came time to make a new one. I made matters worse for myself by insisting to have a little "new!" sticker next to every new post, which would invariably become horribly outdated as I left the blog to rust and rot. >,<
Therefore, with a year of college computer science under my belt and the willingness to set aside my hatred of javascript, I resolved to code a successor.
Since Neocities only hosts static sites, all the programming logic of NEOBLOG has to work on the frontend-- that is, javascript running in your visitors' browsers, on their own computers. I struggled with the morality of making my poor visitors load kilobytes of javascript just to see my blog, but in the end I think the performance impact is pretty minimal.
I decided to use Alpine.js, the littlest javascript framework. I've long had a disdain for JS frameworks; they tend to be horribly bloated and overcomplicated, but the alternative was coding in vanilla JS (read: coding my own, bad framework on accident). Alpine.js is my savior here; its small file size, simplicity, and program-your-logic-in-the-markup workflow make it a breeze to code webpages that do what you expect them to do. My only other dependency was js-yaml, which is horrifyingly large but unfortunately the only YAML parser I could find (ECMA please give us YAML parsing in the standard library please I can't stand JSON).
Here's the new markup, utilizing Alpine:
<template x-for="post in pages[current]">
<article>
<post-header>
<post-dat x-text="post.display_dat"></post-dat>
<post-new x-show="is_new(post, blog.options.days_till_new_is_old)">
<img src="graphix/new.gif" alt="new!">
</post-new>
</post-header>
<post-main x-html="post.content"></post-main>
</article>
</template>
It may look a little more confusing than the old one, but this is only in the html file once instead of being copy-pasted a dozen times. It uses the power of Alpine and the <template> tag to create however many posts are written in our blog.yaml file:
posts:
- display_dat: 11/9/2023 9 PM ET
true_date: 2023-11-09
content: |
<h1>this is an example post</h1>
<p> i love pizza!
display_dat is the date and time as it appears in the post header, true_date is the machine-readable date format used to calculate if a post is "new". content is the actual HTML content of the post. You can put whatever HTML you want in here!
Go to github.com/scumpsmallbrain/neoblog to download the template as a zip file. Github has a super confusing UI that took me ages to get used to personally, so just look for the Releases header, click on that, and download the latest release's zip file.
Unzip this directory and place it inside an offline copy of your site's directory.
Here's a super important detail: To view this page in your browser, you're going to have to run an HTTP server on your computer. An HTTP server is a program that serves a webpage's files to the web. When you upload a page on Neocities, it runs off an HTTP server on Neocities' computers.
Usually, when you open an offline webpage in your browser without running an HTTP server, it works fine. But NEOBLOG needs to fetch the data from that blog.yaml file with Javascript. For security reasons, Javascript isn't allowed to fetch files from your own local machine. (It would suck if you went to a website and it suddenly had access to all of your personal files)
Luckily, there are some really easy ways to do this. If you're using VS Code/Codium, I highly recommend the Five Server plugin. It lets you do all this stuff in one click without much hassle.
Otherwise, the Python runtime comes in with a built-in HTTP server. Once Python is installed, open your site's directory in your command-line terminal and enter python -m http.server. It should start serving your webpage on port 8000. Don't worry, this hasn't opened up your site to the entire internet; you'd need to do port forwarding for that. Open your browser and enter localhost:8000 in the address bar to see your webpage.
Edit the style.css file to your liking, adjusting the blog's look. Did you know CSS supports nested selectors now? I love them, they've seriously made CSS such a joy to code.
The page navigation won't load unless it needs to be there, so keep that in mind if you want to style that, too.
When you're ready to write some blog posts of your own, open blog.yaml. You can check the github page for more info on each parameter, but I think they're pretty self-explanatory.
If you've never coded a YAML file before, here's some things to keep in mind:
-" in front of each new post is important.|" after each content: is important, as it denotes the start of a multiline string which we can write HTML in.If you follow the examples it should work fine!
Upload the new files to your site, and place either blog/index.html or blog/latest.html in an <iframe> on your main page for all to see!