Architecture

Personal website for Joost van der Borg (joostvanderborg.nl), built with Eleventy (11ty v3) and deployed on Netlify.

Overview

Static site generator setup. Content is stored as Markdown with YAML frontmatter, Eleventy transforms it into HTML, and Netlify serves it. Pinboard bookmarks tagged "publish" are automatically pulled in as quicklink posts at build time.

Directory structure

.
├── .eleventy.js          # Eleventy config (ESM)
├── index.js              # Build entry point (runs Pinboard sync, then Eleventy)
├── index.html            # Home page (paginated post list)
├── posts.md              # /posts index page
├── tags.njk              # Auto-generates /tags/<tag>/ pages
├── quicklinks.js         # Pinboard API integration
├── boeken.html           # /boeken/ bookshelf page (books per year, covers on planks)
├── book_cover.js         # `bookcover` shortcode: Open Library covers + physical book size
├── book_list.js          # Bulk book post generator (via Open Library API)
├── book_details.js       # Single-book post generator (legacy, by ISBN)
├── book_search.js        # Book search utility
├── robots.txt
├── netlify.toml          # Netlify build config + cache plugin
├── .pages.yml            # Pages CMS config (Git-based CMS UI, legacy)
├── admin/                # Sveltia CMS (served at /admin/, passthrough-copied)
│   ├── index.html        # Loads Sveltia + custom JS (Open Library lookup, image shortcode button)
│   └── config.yml        # Collections, media settings
│
├── _includes/            # Eleventy layouts
│   ├── template.html     # Base layout (head, nav, body wrapper)
│   ├── post.html         # Blog post layout (gallery support, prev/next nav)
│   ├── book.html         # Book review layout (author, ISBN, star rating)
│   └── post-p5.html      # Post layout + p5.js for interactive/generative posts
│
├── posts/                # All content (Markdown + YAML frontmatter)
│   ├── posts.json        # Sets tags: ["post"] for all posts
│   ├── 2008/ … 2025/     # Blog posts by year/month subdirectories
│   └── quicklinks/       # Auto-generated Pinboard quicklinks (ISO timestamp filenames)
│
├── styles/
│   └── main.css          # Single stylesheet (CSS custom properties, dark mode, responsive grid)
│
├── js/
│   └── p5.min.js         # p5.js library (used by post-p5.html posts)
│
├── uploads/              # Media files (images), organised by year
│   └── 2012/ … 2025/
│
└── netlify/
    └── functions/
        └── scheduled-deploy.js  # Cron function: triggers rebuild 3× per day

Build process

node index.js
  1. grab_pinboard_data()   → fetches Pinboard bookmarks (tag: publish)
                              → writes Markdown files to posts/quicklinks/
  2. Eleventy.write()       → builds everything to _site/

The npm run build / yarn build script calls node index.js. PINBOARD_TOKEN must be set in the environment (via .env locally, Netlify env vars in CI).

Content model

All content lives under posts/ as Markdown with YAML frontmatter. The posts/posts.json file applies tags: ["post"] to everything in the directory tree, making all posts part of the collections.post collection used for the home feed, feeds, and pagination.

Post types

Layout Used for Key frontmatter fields
post.html Blog posts, photo sets, quicklinks title, date, tags, featured, photos[], href (quicklinks)
book.html Book reviews title, author, isbn, olid, cover, rating (1–5), tags
post-p5.html Interactive / generative art posts same as post + postname (used to load <postname>.js)

Photo gallery posts: set featured (single image path) for OG image and photos array (each with url, alt, orientation: landscape|portrait) to render a gallery.

Quicklinks: auto-generated with href pointing to the linked URL; the post.html template renders an outbound link.

Books: rating is 1–5 stars; displayed as ★/☆ in book.html. ISBN links to Open Library. Every book page shows its cover, and /boeken/ (boeken.html) shows all books as a bookshelf per year. Books are selected by layout: book.html, not by tag.

Book covers (book_cover.js, bookcover shortcode): the cover comes from, in order, the cover frontmatter (a local image), the Open Library edition's cover ID, another cover of the same work (the work record's covers, else the first printed edition with a cover, English first; audio/e-book editions are skipped), an Open Library title + author search (this also covers books without ISBN/OLID), or a cover lookup by ISBN/OLID. An olid that is a work ID (OL…W) is handled too. It goes through eleventy-img (160/320/480px, AVIF/WebP/JPEG) into _site/uploads/covers/. If none of these works, a typographic placeholder shows the title and author. On the shelf, a book's height uses the edition's physical_dimensions when known, otherwise an estimate from physical_format (hardcover 24cm, paperback 21cm, mass market 17.8cm, default 21cm). Width is set explicitly from height × the cover's aspect ratio, clamped to 0.55–0.78 so square audiobook covers are cropped to book proportions, and the page edge's thickness follows number_of_pages. Open Library JSON and images are cached for a year in .cache (kept between Netlify builds), so only new books hit the network. To fix a wrong or missing cover, set cover:. Book pages without a featured image use their cover as og:image (the bookcoverMeta shortcode in template.html). The site nav links to /boeken/.

URLs come from the file path (no global permalink), e.g. posts/2024/03/foo.md → /posts/2024/03/foo/. Moving a file changes its URL unless it has an explicit permalink.

Frontmatter reference

---
title: "Post title"
date: "2024-06-15"
layout: "post.html"          # post.html | book.html | post-p5.html
tags: ["fotos"]              # "post" is added by posts/posts.json
postname: "my-post-slug"     # used for p5.js script loading; also in book posts
description: "..."           # OG/meta description
featured: "/uploads/2024/01/image.jpg"   # OG image + inline image
photos:                      # gallery
  - url: "/uploads/..."
    alt: "..."
    orientation: landscape   # landscape | portrait
href: "https://..."          # quicklinks only: external URL
# Book-specific:
author: "Author Name"
isbn: "9781234567890"
rating: 4                    # 1–5
cover: "/uploads/2025/01/cover.jpg"   # optional; overrides Open Library
---

Templates and rendering

All layouts chain via layout: frontmatter. The rendering stack:

post.html / book.html / post-p5.html
  └── template.html   (base: <html>, <head>, <nav>, <main>)

Templates use Liquid (.html files) and Nunjucks (.njk files). Eleventy supports both. Liquid is used for the main layouts; tags.njk uses Nunjucks explicitly.

Eleventy configuration (.eleventy.js)

Feeds

Styling

Single file: styles/main.css. Approach:

Automated deploys (Netlify)

netlify/functions/scheduled-deploy.js is a Netlify scheduled function that fires at 11:06, 16:06, and 21:06 UTC daily. It POSTs to a Netlify deploy hook (env var DEPLOY_HOOK), triggering a rebuild to pull in new Pinboard quicklinks.

netlify.toml enables the netlify-plugin-cache plugin to persist:

Content management

Sveltia CMS (/admin/)

Sveltia CMS is configured in admin/config.yml, with custom JS in admin/index.html. It uses the GitHub backend and commits directly to main. To sign in, use a fine-grained GitHub token (Contents: read/write), or set up GitHub OAuth through Netlify (Project configuration → Security → OAuth, callback https://api.netlify.com/auth/done).

Pages CMS (legacy)

.pages.yml configures Pages CMS, a Git-based headless CMS. It exposes the posts/ directory as a collection with fields for all frontmatter keys, a layout selector (book.html / post.html), and image upload to uploads/.

Utility scripts

These scripts are run manually outside the build to create content stubs:

Environment variables

Variable Used by Purpose
PINBOARD_TOKEN quicklinks.js Pinboard API authentication
DEPLOY_HOOK netlify/functions/scheduled-deploy.js Netlify build hook URL