Building a static blog is hard

I’ve finally decided to start an new blogs (there were two perviously but didn’t last). Not only was my procrastination and perfectionism preventing me from doing it but also because building a correct and simple static blog is hard and complicated.

I do have higher standards for anything technology related, and when I want to do something, I want to do it right.

Some goals: to break it down.

• simple and easy to maintain
• accessible
• performant and energy efficient
• human and content centric
• ever-lasting

There is a whole huge rabbit holes regarding to indieweb, polygon xhtml, gemini, tar compatibility, and more strict standards that I’m not ready to jump in right now. Maybe for the future.

these immediately yield some results:

• lightweight and loads fast, every page needs to be under 100kb
• responsive and fits on all screens
• No links resources or only from the same domain (same tld)
• No CDN / Captchas / geographical restrictions
• No JavaScript
• Works in text browsers like lynx
• Screenshots of whole page can be saved (no weird scrolling, fixed panels etc.)
• If I save the page as HTML, it can be viewed offline later (including all important assets)
• No tracking or affilate links
• No ad system, no aggressive adverts (content:advert ratio should be somehow 90:10 or better)
• Meaningful titles and links (not misleading and if I bookmark the page, I can find it by keyword later)
• Images have alternative text and / or description
• cited or borrow content from other authors has proper references
• links to downloadable files say also format and size, e.g. “technical documentation (PDF, 560 KiB, 84 pages)”
• all pages have a timestamp / date of creating and last change
• says who is the author (may be a pseudonyme) and what is the purpose of the website; something like impressum
• catalog of all pages or at least news are available as RSS/Atom/RDF machine-readable format
• no annoying cookie consents, newsletters, pop-ups, paywalls etc.
• generated content (AI and other) is clearly marked (if any) and differentiated from human-created content
• no automatically playing videos or sounds; no autoplay (unless explicitly turned on by the user)
• only use gTLB domains

Toolchains I need:

• A linter and formatter for both markdowns and html templates.
• Validators that checks the following:
  • my spelling
  • html formats
  • css formats
  • link availablility
• A template engine and a static site generator that does the following (ordered by priority):
  • correctly render my markdown to html
  • multilingual support (yes I’m bilingual, and I’d like to write in another language sometime)
  • generates a table of content (I tend to write long posts)
  • renders latex formula to proper MathML (I want to write some math). Since it’s already widely adopted by major browser engines I see no reason to choose Katex.
  • renders footnotes properly, i.e. github footnote style. This is usually an issue for Rust SSGs that use pulldown-cmark.
  • generates both atom and rss feeds
  • generates sitemap
  • proper code syntax highlight
  • performant
• A simple file watcher and local http server for rapid dev feedback loop
• An minifier for cutting down the html sizes.
• An CI system that automatically builds and deploys my sites
• A static host service that serves my site.

It’s in 2024 and there are hundreds of all kinds SSG and I’m amazed by the fact that no one ticks all these boxes. For now I’m settled with blades, a rust based SSG that uses mustache as its templating solution. It’s fast, simple to use, generates atom, rss, and sitemap, has rudimentory support for mathml and syntax highlighting. Though it doesn’t not support github footnote style, table of content. And it’s currently not actively maintained (the author left github). We’ll see how lone it goes, and when it fails me I might start a new SSG on my own.

Current workflow

I’m using Nix to save my life.

Here is the flake.nix of this website:

{
  description = "My personal website";
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.05";
  inputs.flake-utils.url = "github:numtide/flake-utils";

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let pkgs = nixpkgs.legacyPackages.${system};
      in {
        packages.website = pkgs.stdenv.mkDerivation {
          name = "blog";
          src = self;
          buildPhase = "${pkgs.hugo}/bin/hugo";
          installPhase = "cp -r public $out";
        };

        defaultPackage = self.packages.${system}.website;
        devShells.default = pkgs.mkShell { packages = [ pkgs.hugo ]; };
      });
}

I use sourcehut to host my website. When I pushed to the git repository, it will be deployed automatically using the sourcehut build service. In the build, nix build uses flake.nix to create exactly same environment as in development:

image: nixos/latest
oauth: pages.sr.ht/PAGES:RW
packages:
- nixos.hut
environment:
  NIX_CONFIG: experimental-features = nix-command flakes
  site: yejun.dev
tasks:
- package: |
    cd $site
    nix build
    tar -C result -cvz . > ../site.tar.gz    
- upload: |
    hut pages publish -d $site site.tar.gz   

Some results

• It’s fast, it achieved perfect scores in PageSpeed Insights and Yellow Lab Tools report.
• Its carbon footprint is low. Said by Website Carbon, Ecogarder, and Green Web Foundation.
• It’s secure and repects all visitors’ privacy. There are no trackers, cookies, or ads. I’ve added the recommended security headers. It’s HTTPS-only.

Todos

• changelogs based on git commits
• try cloudflare page/xmit
• switch to deSEC for DNS manager

Some resources and inspiration

The clubs:

• The 512KB Club
• The 250KB Club
• 1MB Club
• 1KB Club
• The no-JS Club
• The Darktheme Club