path: root/posts/blarg.md



# My simple blog engine blarg

All the pages on this website are built using my simple blog engine [blarg](https://codeberg.org/JustineSmithies/blarg). It is a combination of all the best bits of both [blog.sh](https://github.com/karlb/karl.berlin) and [barf](https://git.sr.ht/~bt/barf) plus I've added some of my own touches too.

## Why didn't I just use one of the above?

I found out about barf after seeing [hamblingreen](fosstodon.org/@hamblingreen) post about their new blog and absolutely loved the idea of a simple blog site that could I could write posts in markdown with. I instantly cloned the barf repo and started to play about with it but quickly noticed that it didn't quite do things as I'd like and also had a few bugs / issues which would need to be resolved.
As usual I just can't do things the easy way so set out to create blarg my own simple blog engine and took inspiration from both blog.sh and barf. I also needed to make changes to how the dates were displayed on the index and on all posts. Git history is used to form published on and updated dates on blog posts to keep things nice and easy.
I have also ironed out the html issues too so my blog now passes all three W3C validation checks.

HTML:
[https://validator.w3.org/nu/](https://validator.w3.org/nu/)

CSS:
[https://jigsaw.w3.org/css-validator/](https://jigsaw.w3.org/css-validator/)

Atom feed:
[https://validator.w3.org/feed/](https://validator.w3.org/feed/)

## Requirements

Before jumping deeper into it, I made a list of my basic requirements:

- Low maintenance
- Low barrier to create content (markdown)
- Low requirements on the client (web browser, internet connection, RAM, CPU)
- Shows creation and update timestamps of posts
- RSS feed

## How these constraints are acheived

### Low maintenance

- Avoid dependencies: only a POSIX shell and a markdown converter are required. Dependencies always increase the maintenance burden.
- Static files: hosting static files is much easier to do reliably than hosting dynamic content

### Low barrier to create content

- Use markdown: when writing markdown I can mostly avoid thinking about the syntax and focus on the content
- Automatically generate timestamps: generating the timestamps from the git history allows me to just create posts without needing any templates or front matter to provide this data. I also can't forget to update these timestamps.

### Low requirements on the client

This is mostly solved by not doing anything complicated. Not adding any JS and CSS frameworks keeps the size small. Not setting a font size and not disallowing zooming makes the text readable on a wide variety of devices and by people of bad eye sight. Just using basic HTML and a few lines of CSS allows old or limited browsers and slow computers to display the page easily. I could go on for a long time here, but I'm sure you get the concept.

### RSS Feed

Having an RSS feed (an [Atom](https://en.wikipedia.org/wiki/Atom_(Web_standard)) feed to be precise) is a must for me. I really love RSS and in my opinion RSS support is an essential part of a blog. I was shocked to learn that some blog engines need plugins to get RSS support!
Writing something that is nearly a valid Atom feed is pretty easy. Just take the [example Atom feed](https://validator.w3.org/feed/docs/atom.html#sampleFeed) and fill in your own values.

## Results

### The HTML output

* No JS, no tracking, no custom fonts
* No external CSS
* Minimal styling
* Light weight pages

### The blog script

You can find the [code of the resulting script](https://codeberg.org/JustineSmithies/blarg) on github. The blog you are currently viewing is part of the same repository and serves as example content.

To make the script work as intended, you should adhere to the following rules:

- Make sure to empty out the contents of the `build`, `posts`, `pages` and `public` folders so you don't end up with my content.
- Use git and don't edit history after publishing. This is required for the automatic timestamp generation.
- All posts except the `index.md` have a title using the `# ` syntax at the beginning of the document. This title is used for the HTML title tag and for the post titles in the article listing and RSS feed.
- To set the title for `index.html` edit the text between `<title>` and `{{TITLE}}</title>` of the file `header.html`. Do not delete the `{{TITLE}}` text as this is used for setting the title on all pages of your site.
- `header.html` contains an absolute link to your `atom.xml`, including a hostname you control. This is necessary to build a correct atom feed.
- Also make sure to edit the section in `header.html` between the `<nav></nav>` tags to suit your site too.
- All images and other content to be published go into the `public` folder.

Feel free to contact me if you have any questions. If you want to use it for your own site, I can give some guidance. Since I don't expect many users, this is less effort than writing and maintaining good documentation.
# My simple blog engine blarg

All the pages on this website are built using my simple blog engine [blarg](https://codeberg.org/JustineSmithies/blarg). It is a combination of all the best bits of both [blog.sh](https://github.com/karlb/karl.berlin) and [barf](https://git.sr.ht/~bt/barf) plus I've added some of my own touches too.

## Why didn't I just use one of the above?

I found out about barf after seeing [hamblingreen](fosstodon.org/@hamblingreen) post about their new blog and absolutely loved the idea of a simple blog site that could I could write posts in markdown with. I instantly cloned the barf repo and started to play about with it but quickly noticed that it didn't quite do things as I'd like and also had a few bugs / issues which would need to be resolved.
As usual I just can't do things the easy way so set out to create blarg my own simple blog engine and took inspiration from both blog.sh and barf. I also needed to make changes to how the dates were displayed on the index and on all posts. Git history is used to form published on and updated dates on blog posts to keep things nice and easy.
I have also ironed out the html issues too so my blog now passes all three W3C validation checks.

HTML:
[https://validator.w3.org/nu/](https://validator.w3.org/nu/)

CSS:
[https://jigsaw.w3.org/css-validator/](https://jigsaw.w3.org/css-validator/)

Atom feed:
[https://validator.w3.org/feed/](https://validator.w3.org/feed/)

## Requirements

Before jumping deeper into it, I made a list of my basic requirements:

- Low maintenance
- Low barrier to create content (markdown)
- Low requirements on the client (web browser, internet connection, RAM, CPU)
- Shows creation and update timestamps of posts
- RSS feed

## How these constraints are acheived

### Low maintenance

- Avoid dependencies: only a POSIX shell and a markdown converter are required. Dependencies always increase the maintenance burden.
- Static files: hosting static files is much easier to do reliably than hosting dynamic content

### Low barrier to create content

- Use markdown: when writing markdown I can mostly avoid thinking about the syntax and focus on the content
- Automatically generate timestamps: generating the timestamps from the git history allows me to just create posts without needing any templates or front matter to provide this data. I also can't forget to update these timestamps.

### Low requirements on the client

This is mostly solved by not doing anything complicated. Not adding any JS and CSS frameworks keeps the size small. Not setting a font size and not disallowing zooming makes the text readable on a wide variety of devices and by people of bad eye sight. Just using basic HTML and a few lines of CSS allows old or limited browsers and slow computers to display the page easily. I could go on for a long time here, but I'm sure you get the concept.

### RSS Feed

Having an RSS feed (an [Atom](https://en.wikipedia.org/wiki/Atom_(Web_standard)) feed to be precise) is a must for me. I really love RSS and in my opinion RSS support is an essential part of a blog. I was shocked to learn that some blog engines need plugins to get RSS support!
Writing something that is nearly a valid Atom feed is pretty easy. Just take the [example Atom feed](https://validator.w3.org/feed/docs/atom.html#sampleFeed) and fill in your own values.

## Results

### The HTML output

* No JS, no tracking, no custom fonts
* No external CSS
* Minimal styling
* Light weight pages

### The blog script

You can find the [code of the resulting script](https://codeberg.org/JustineSmithies/blarg) on github. The blog you are currently viewing is part of the same repository and serves as example content.

To make the script work as intended, you should adhere to the following rules:

- Make sure to empty out the contents of the `build`, `posts`, `pages` and `public` folders so you don't end up with my content.
- Use git and don't edit history after publishing. This is required for the automatic timestamp generation.
- All posts except the `index.md` have a title using the `# ` syntax at the beginning of the document. This title is used for the HTML title tag and for the post titles in the article listing and RSS feed.
- To set the title for `index.html` edit the text between `<title>` and `{{TITLE}}</title>` of the file `header.html`. Do not delete the `{{TITLE}}` text as this is used for setting the title on all pages of your site.
- `header.html` contains an absolute link to your `atom.xml`, including a hostname you control. This is necessary to build a correct atom feed.
- Also make sure to edit the section in `header.html` between the `<nav></nav>` tags to suit your site too.
- All images and other content to be published go into the `public` folder.

Feel free to contact me if you have any questions. If you want to use it for your own site, I can give some guidance. Since I don't expect many users, this is less effort than writing and maintaining good documentation.