vknobelsdorff.com

Reorganizing my dotfiles

2026-04-01T11:01:52Z

With the latest additions to my homelab I needed to reorganize my dotfiles and improve the process of bootstrapping a new machine with the required tools and configuration.

The challenge

Managing dotfiles across multiple machines is straightforward until the machines start diverging. My setup spans a personal MacBook, a work MacBook, and a Linux machine. They share a lot of configuration but differ in identity (email, signing keys), OS specifics, and machine-specific tooling. I wanted one repository that handles all of them without a mess of conditionals scattered through every config file.

The structure

The solution is a four-layer directory hierarchy managed by GNU Stow. Each layer is applied on top of the previous one:

00base/          # applied to every machine
01os/<os>/       # macos or linux
02identity/<id>/ # personal or work
03hosts/<host>/  # machine-specific overrides

Within each layer, packages are plain directories named after the tool they configure. A package contains the files in the same relative path they should end up at in $HOME. For example, 00base/eza/.config/eza/ maps to ~/.config/eza/. Stow creates symlinks, so the actual files always live in the dotfiles repository.

The .stowrc file at the root sets the target and a few ignore patterns:

--target="~"
--ignore='.DS_Store'
--ignore='\.gitkeep$'
--no-folding

--no-folding is important: without it Stow may symlink an entire directory rather than the files inside it, which breaks the layering because a later layer cannot add files inside a directory that is itself a symlink.

The install script

The install script at the root of the repository handles bootstrapping. It auto-detects the hostname and OS, maps them to an identity, and stows all four layers in order:

stow_all_in "00base"
stow_all_in "01os/$OS_GROUP"
stow_all_in "02identity/$IDENTITY"
stow_all_in "03hosts/$HOST_KEY"

The host-to-identity mapping is a simple associative array at the top of the script:

declare -A HOST_TO_IDENTITY
HOST_TO_IDENTITY=(
  [work-mbp]=work
  [mbp-dvk]=personal
  [arch-mbp]=personal
)

Hostname normalization converts the raw hostname -s output to lowercase with hyphens, making it case-insensitive and consistent across platforms.

Before stowing a package the script unstows it first (stow -D). This ensures stale symlinks from a previous run are cleaned up before new ones are created. Any package directory prefixed with _ is skipped entirely, which is useful for work-in-progress packages that should not be deployed yet.

The script also supports a few useful flags:

./install --dry-run            # preview without making changes
./install -p "01os/macos/bin"  # stow a single package manually
./install -H mbp-dvk           # override the detected hostname

Adding a new machine

To add a new machine you add a mapping in the HOST_TO_IDENTITY array, create a 03hosts/<hostname>/ directory with any machine-specific packages, and run ./install. If the machine uses a new OS or identity that does not yet have a layer directory, those are created too. Machines that share all configuration with an existing host can skip the host layer entirely and rely only on the base, OS, and identity layers.

Cleaning up

I also added a clean-env script which removes all symlinks by running stow -D against every known package across all layers. It covers all currently known hosts so it handles cleanup on any of the registered machines.

This structure keeps the repository tidy: every file has an obvious home, the layers compose predictably, and bootstrapping a new machine is a single command.

Expanding the concept

Since the concept worked quite well I applied the same pattern inside individual tool configurations, most notably zsh.

The three main zsh entry points (.zshenv, .zprofile, .zshrc) each contain nothing but a sourcing loop:

setopt null_glob
for conf in "$HOME/.zshrc.d/"*.zsh; do
  source "${conf}"
done
unsetopt null_glob
unset conf

.zshenv sources everything in ~/.zshenv.d/, .zprofile sources ~/.zprofile.d/, and .zshrc sources ~/.zshrc.d/. The null_glob option prevents an error when a directory is empty or does not exist. Each file in those directories is a standalone numbered snippet, which means different stow layers can drop files into the same directory and they compose at shell startup without any of them knowing about the others.

The base layer (00base/zsh/) provides the numbered files that cover the universal configuration:

.zshenv.d/00-path.zsh       # PATH setup
.zshenv.d/01-tools.zsh      # tool environment variables
.zshenv.d/02-editor.zsh     # EDITOR / VISUAL

.zprofile.d/01-tools.zsh    # login-time tool init (homebrew, etc.)

.zshrc.d/00-zinit.zsh       # plugin manager and plugins
.zshrc.d/02-theme.zsh       # prompt theme
.zshrc.d/03-tools.zsh       # interactive tool init (fzf, zoxide, etc.)
.zshrc.d/04-completions.zsh # completion setup
.zshrc.d/05-functions.zsh   # autoloaded functions
.zshrc.d/06-history.zsh     # history settings
.zshrc.d/07-shell-options.zsh
.zshrc.d/10-alias.zsh       # universal aliases
.zshrc.d/11-keybindings.zsh # key bindings
.zshrc.d/12-prompt.zsh      # prompt init

The numeric prefix controls load order. Low numbers run first, leaving the high end of the namespace for identity and host overlays.

The work identity (02identity/work/zsh/) stows a single file into that same directory:

.zshrc.d/99-work.zsh

That file is sourced last and adds everything that only makes sense on a work machine. Because it runs at number 99 it can safely override or extend anything set earlier.

The personal host overlay (03hosts/mbp-dvk/zsh/) follows the same pattern with its own 99-personal.zsh.

Adding a new work-only shell feature means creating or editing a file in 02identity/work/zsh/.zshrc.d/. Adding something machine-specific goes into 03hosts/<hostname>/zsh/.zshrc.d/. Neither touches the base configuration, and the ordering guarantees the base is always established before any overlay runs.

Leveraging advanced gitconfig customization options

2026-04-01T11:00:30Z

The .gitconfig was a configuration file I never gave much attention. When I migrated away from GitHub to self-hosting on Forgejo (see Moving away from GitHub) the need arose to better organize the configurations deployed across my various machines. Reading through the documentation I found one option in particular I was not aware of: conditional includes.

The problem

I use multiple git forges. On my personal machine I push to both GitHub and my self-hosted Forgejo instance. On my work machine I additionally push to a corporate GitLab. Each forge has its own email address, signing key, and commit settings. I wanted all of this handled automatically without having to set it per repository.

includeIf to the rescue

Git's includeIf directive lets you pull in a separate config file only when a condition is met. The condition I use is hasconfig:remote.*.url, which matches against any remote URL in the current repository:

[include]
    path = ~/.gitconfig-base
[includeIf "hasconfig:remote.*.url:git@github.com*/**"]
    path = ~/.gitconfig-github
[includeIf "hasconfig:remote.*.url:git@mydomain.tld*/**"]
    path = ~/.gitconfig-forgejo
[includeIf "hasconfig:remote.*.url:ssh://git@corporate.tld/**"]
    path = ~/.gitconfig-work

The base config is always included first and sets the defaults: my default name, email, delta pager settings, rebase options, push behavior, and so on. The conditional includes then override only what needs to differ per forge, mainly the email and SSH signing key:

# .gitconfig-forgejo
[user]
    name = ...
    email = ...
    signingkey = ssh-ed25519 AAAAC3...
[commit]
    verbose = true
    gpgsign = true

The ordering matters

The base config deliberately turns off commit signing (gpgsign = false). The conditional includes then turn it back on only for the forges where I have signing keys set up. Because git applies includes in order and later values override earlier ones, placing the conditional includes after the base include ensures the per-forge settings win.

Conclusion

This setup means I never touch per-repository git config for identity. Cloning a repo from GitHub automatically uses the GitHub email and signing key. Cloning from Forgejo picks up the Forgejo settings. Everything is driven by the remote URL.

Quickly switch network profiles on macOS

2026-04-01T10:59:50Z

My network infrastructure is, thanks to my homelab, probably a bit more involved than for the average user. I maintain a VPN network, custom DNS servers, and both Wi-Fi and Ethernet connections. When switching workplaces I constantly have to switch network settings. macOS offers Network Locations which first looked like the answer, but they are too limited for my needs. So I built a small script around the existing macOS CLIs.

What I needed

My typical network contexts each require a different combination of settings:

Home: Wi-Fi on DHCP, DNS pointing at my homelab resolvers, VPN off
Work: Wi-Fi on DHCP, system default DNS, VPN off
Home Ethernet: Ethernet on DHCP, custom DNS, Wi-Fi off
Modem Management: Ethernet with a manual static IP for accessing my modem's admin interface, no custom DNS
VPN: Wi-Fi on DHCP, VPN on

Network Locations can store some of this but not all of it. DNS overrides and VPN toggling are outside what they handle cleanly.

The script

I created a script called netprofile. It wraps three macOS tools: networksetup for IP and DNS configuration, scutil for VPN control, and service validation using networksetup -listallnetworkservices.

The script is built around a set of composable low-level functions:

set_dns "Wi-Fi" "192.168.1.10" "192.168.1.11"    # set DNS servers
set_dns "Wi-Fi" "empty"                          # clear DNS back to default
set_wifi "Wi-Fi" dhcp                            # enable Wi-Fi with DHCP
set_wifi "Wi-Fi" off                             # turn Wi-Fi off
set_ethernet "Ethernet USB" manual "192.168.254.99" "255.255.255.0" "192.168.254.1"
set_vpn "homelab" on
set_vpn "homelab" off

Each function handles only one concern. set_wifi calls networksetup -setairportpower and optionally networksetup -setdhcp or networksetup -setmanual. set_vpn uses scutil --nc start and scutil --nc stop, always stopping before starting to ensure a clean state.

The profiles themselves are just case branches in apply_profile that call these primitives:

Home)
    set_wifi "$WIFI_SERVICE" dhcp
    set_ethernet "$ETH_SERVICE" off
    set_dns "$WIFI_SERVICE" "$DNS01" "$DNS02"
    set_vpn "$VPN_NAME" off
    ;;

Service validation

Before applying any profile the script checks that the named services actually exist on the current machine:

check_service_exists() {
  local service="$1"
  if ! networksetup -listallnetworkservices | sed '1d' | grep -Eq "^\*?$service$"; then
    err "Network service '$service' not found."
    exit 1
  fi
}

The sed '1d' strips the header line from networksetup output. The regex accounts for inactive services, which networksetup prefixes with an asterisk.

Usage

The script supports three modes:

netprofile              # interactive select menu
netprofile Home         # apply profile directly
netprofile --list       # print available profiles

The interactive mode uses bash's built-in select which presents a numbered menu. This is useful when running from a launcher or when I forget the exact profile name.

The service names (Wi-Fi, Ethernet USB) and the VPN name (homelab) are defined as variables at the top of the script. Adjusting for a different machine means changing those four lines.

Alfred integration

Typing netprofile Home in a terminal is already fast, but I wanted to trigger it without leaving whatever I was doing. Alfred is my launcher for everything, so the natural step was to build a small workflow around the script.

The workflow uses a List Filter as its input. Each profile name (Home, Work, Home Ethernet, Modem Management, VPN) is an entry in the list with a matching keyword and subtitle. Alfred's fuzzy matching means typing hom is enough to surface both Home and Home Ethernet instantly.

The List Filter passes the selected profile title to a Run Script action:

/usr/local/bin/netprofile "$1"

Using the full path to the script avoids any PATH issues since Alfred does not source the shell environment. The script runs, applies the profile, and exits silently. A Post Notification action at the end of the chain sends a brief macOS notification confirming which profile was activated, so there is visible feedback without having to open a terminal.

The result is: open Alfred, type two or three characters, press Enter, and the network switches. The whole interaction takes about two seconds.

Building a custom fzf picker

2026-04-01T10:58:44Z

With the addition of more machines into my homelab my SSH config grew quite large. SSHing into one of my machines is something I do daily, and while the config and keys make it easy, I wanted something faster. I already use fzf heavily for terminal history and directory switching. Since fzf follows the Unix philosophy and does exactly one thing well, fuzzy finding, what gets searched is entirely up to you. So I wrote a small script that fuzzy-finds SSH targets from my config.

Parsing the SSH config

The script reads ~/.ssh/config and extracts all non-wildcard Host entries using awk:

mapfile -t hosts < <(
  awk '/^Host / {for(i=2;i<=NF;i++) if ($i !~ /\*/) print $i}' "$ssh_config"
)

The !~ /\*/ filter drops catch-all patterns like Host * which are configuration defaults rather than actual targets. Each matching token becomes an element in the hosts array.

The picker

With the host list ready, fzf takes over. The script behaves differently depending on the environment.

Inside tmux, it uses fzf-tmux to open a centered popup at 40% of the screen:

selected_host=$(printf '%s\n' "${hosts[@]}" | fzf-tmux -p 40%,40% \
  --gutter=' ' \
  --color=current-fg:blue \
  --color=hl:yellow \
  --no-sort \
  --border-label ' ssh hosts ' \
  --prompt '> ' \
)

Outside tmux, it falls back to inline fzf with --height=40% --reverse.

Opening the session

Once a host is selected, the script opens it in a named tmux session:

if [[ -n "${TMUX-}" ]]; then
  tmux new-session -d -s "$selected_host" "ssh $selected_host"
  tmux switch-client -t "$selected_host"
else
  exec tmux new-session -s "$selected_host" "ssh $selected_host"
fi

When already inside tmux, it creates the session detached first and then switches to it. This avoids the nested tmux situation while still landing in a dedicated session per host. When called from outside tmux it starts a new tmux session directly in the foreground.

WezTerm integration

If the script is running inside a WezTerm pane (detected via $WEZTERM_PANE and $WEZTERM_UNIX_SOCKET), it delegates to WezTerm's own SSH workspace picker instead by sending a user-var event via an OSC escape sequence:

printf '\033]1337;SetUserVar=open-wezterm-ssh-picker=%s\007' "$(printf '1' | base64)"

This triggers a Lua plugin on the WezTerm side that handles the picker natively, keeping the experience consistent with the rest of the WezTerm workspace workflow. I also went ahead and created a keybinding for it so I can quickly toggle the picker:

local wezterm = require("wezterm")
local sessionizer = require("plugins.sessionizer")

local M = {}

local function spawn_ssh_workspace(window, pane, host)
  local ws_name = "ssh:" .. host
  window:perform_action(
    wezterm.action.SwitchToWorkspace({
      name = ws_name,
      spawn = {
        label = "SSH " .. host,
        cwd = wezterm.home_dir,
        args = { "ssh", host },
      },
    }),
    pane
  )
end

local ssh_workspace_schema = {
  options = {
    title = "Choose SSH Host",
    prompt = "SSH host: ",
    always_fuzzy = true,
    callback = function(inner_window, inner_pane, id, _)
      if id then spawn_ssh_workspace(inner_window, inner_pane, id) end
    end,
  },
  sessionizer.SSHHosts {},
}

function M.run_picker(window, pane)
  window:perform_action(sessionizer.show(ssh_workspace_schema), pane)
end

function M.show_picker()
  return wezterm.action_callback(M.run_picker)
end

wezterm.on("ssh_workspace_picker", function(window, pane)
  M.run_picker(window, pane)
end)

wezterm.on("user-var-changed", function(window, pane, name, value)
  if name == "open-wezterm-ssh-picker" then
    M.run_picker(window, pane)
  end
end)

return M

// ...
table.insert(config.keys, { key = 's', mods = 'SUPER|SHIFT', action = ssh_picker.show_picker() })

The result is a beautiful, easily accessible and fast SSH picker in my favourite terminal emulator:

Collapsible component in SwiftUI

2026-04-01T10:32:42Z

As already stated in my previous posts I wanted to match the look and feel of Reeder Classic for my personal RSS reader app. One rather tricky challenge I faced was to recreate the collapsible component to expand or collapse a folder of rss feeds inside a List. Since then I found this excellent blog post which seems to solve this exact issue: Expanding Animations in SwiftUI Lists. Unfortunately this was not published when I tackled this problem and I came up with a different solution.

Without further ado lets look at the implementation and highlight some of the key components:

import SwiftUI

extension EnvironmentValues {
    @Entry var dsCollapsibleDepth: Int = 0
}

struct DSCollapsible<Header: View, Content: View>: View {
    @Environment(\.theme) private var theme
    @Environment(\.dsCollapsibleDepth) private var depth
    
    @Binding private var isExpanded: Bool
    private let action: (() -> Void)?
    private let header: Header
    private let content: () -> Content
    private let accessibilityLabel: () -> Text
    
    init(
        isExpanded: Binding<Bool>,
        action: (() -> Void)? = nil,
        accessibilityLabel: @escaping () -> Text,
        @ViewBuilder header: () -> Header,
        @ViewBuilder content: @escaping () -> Content
    ) {
        self._isExpanded = isExpanded
        self.action = action
        self.accessibilityLabel = accessibilityLabel
        self.header = header()
        self.content = content
    }
    
    private func headerAction() {
        if let action {
            action()
        } else {
            withAnimation(theme.tokens.animation.collapsible) {
                isExpanded.toggle()
            }
        }
    }
    
    var body: some View {
        VStack(alignment: .leading, spacing: 0) {
            Button(action: headerAction) {
                HStack(spacing: 0) {
                    HStack {
                        header
                            .font(theme.tokens.font.button)
                            .foregroundStyle(.text.primary)
                        Spacer()
                    }
                    .padding(.leading, theme.tokens.spacing.s + CGFloat(depth) * theme.tokens.spacing.s)
                    .padding(.vertical, theme.tokens.spacing.s)
                    .frame(maxWidth: .infinity, minHeight: 44)

                    DSIcon("chevron.right")
                        .font(theme.tokens.font.button)
                        .foregroundStyle(.text.secondary)
                        .rotationEffect(.degrees(isExpanded ? 90 : 0))
                        .animation(theme.tokens.animation.collapsible, value: isExpanded)
                        .padding(.trailing, theme.tokens.spacing.s)
                        .padding(.vertical, theme.tokens.spacing.s)
                        .frame(minHeight: 44)
                        // When there is a navigation action, intercept chevron taps
                        // so they only toggle expand/collapse, not navigate.
                        .highPriorityGesture(action != nil ? TapGesture().onEnded {
                            withAnimation(theme.tokens.animation.collapsible) {
                                isExpanded.toggle()
                            }
                        } : nil)
                }
                .contentShape(.rect)
            }
            .buttonStyle(DSListItemStyle())
            .accessibilityLabel(accessibilityLabel())
            .accessibilityAddTraits(.isButton)
            .accessibilityValue(isExpanded ? Text("Expanded") : Text("Collapsed"))
            .accessibilityAction(named: isExpanded ? Text("Collapse") : Text("Expand")) {
                withAnimation(theme.tokens.animation.collapsible) { isExpanded.toggle() }
            }
            
            VStack(spacing: 0) {
                if isExpanded {
                    VStack(spacing: 0) {
                        content()
                    }
                    .environment(\.dsCollapsibleDepth, depth + 1)
                    .transition(.opacity.combined(with: .move(edge: .top)))
                }
            }
            .clipped()
        }
        .dsSectionCardStyle(.transparent)
    }
}

struct DSCollapsibleSection<Content: View>: View {
    @State private var isExpanded: Bool
    private let title: TextContent
    private let action: (() -> Void)?
    private let content: () -> Content
    
    init(
        _ title: LocalizedStringKey,
        initiallyExpanded: Bool = true,
        action: (() -> Void)? = nil,
        @ViewBuilder content: @escaping () -> Content
    ) {
        self.title = .localized(title)
        self._isExpanded = State(initialValue: initiallyExpanded)
        self.action = action
        self.content = content
    }
    
    init(
        verbatim title: String,
        initiallyExpanded: Bool = true,
        action: (() -> Void)? = nil,
        @ViewBuilder content: @escaping () -> Content
    ) {
        self.title = .verbatim(title)
        self._isExpanded = State(initialValue: initiallyExpanded)
        self.action = action
        self.content = content
    }
    
    @_disfavoredOverload
    init(
        _ title: String,
        initiallyExpanded: Bool = true,
        action: (() -> Void)? = nil,
        @ViewBuilder content: @escaping () -> Content
    ) {
        self.title = .verbatim(title)
        self._isExpanded = State(initialValue: initiallyExpanded)
        self.action = action
        self.content = content
    }
    
    var body: some View {
        DSCollapsible(isExpanded: $isExpanded, action: action, accessibilityLabel: { title.textView }) {
            title.textView
        } content: {
            content()
        }
        .dsSectionCardStyle(.transparent)
    }
}

The non obvious solution to animation issues I had is replicated in these few lines:

VStack(spacing: 0) {
    if isExpanded {
        VStack(spacing: 0) {
            content()
        }
        .environment(\.dsCollapsibleDepth, depth + 1)
        .transition(.opacity.combined(with: .move(edge: .top)))
    }
}
.clipped()

Without the clipping of the outer VStack the expanded content would always animate in weird and non obvious ways. The fix is to provide a stable anchor to the SwiftUI layout system which is rendered regardless of the isExpanded flag.

Also you might have noticed the dsCollapsibleDepth environment value. This environment value allows me to nest collapsible components. For each nesting the depth is increased by 1 and the rendered item then can read this information and use it for setting the correct padding:

struct DSListItem<Content: View>: View {
    var body: some View {
        Button(action: action) {
            content
                .frame(maxWidth: .infinity, alignment: .leading)
                .padding(.leading, theme.tokens.spacing.s + CGFloat(depth) * theme.tokens.spacing.s) // <-- this is the important part
                .padding(.trailing, theme.tokens.spacing.s)
                .padding(.vertical, theme.tokens.spacing.s)
                .frame(minHeight: 44)
        }
        .containerValue(\.dsSuppressTrailingDivider, true)
        .buttonStyle(DSListItemStyle())
        .dsSectionCardStyle(.transparent)
    }
}

With this in place we can nest this component freely:

DSList {
    Section {
        DSCollapsibleSection("Folders") {
            DSCollapsibleSection("Tech") {
                DSListItem(action: {}) {
                    Text("Some feed name")
                }
            }
        }
    } header: {
        Text("Nested Collapsible")
    }
}

If we would use this component in the builtin List component from SwiftUI I think we would need to apply the fixes from the referenced blog post above. (e.g. using an Animatable view that can animate its height). Since I am using my custom DSList component (showcased in SwiftUI Container API) this works flawlessly however.

I really had hoped to be able to use the existing DisclosureGroup API but unfortunately Apple does not provide any customization possibilities for it. A custom DisclosureGroup style would be a very welcome addition to the API surface in my opinion. Until then I am using my custom component.

If you want to see the component in action and how it behaves head over to my other post Building an iOS RSS reader where I included a demo video of the application.

SwiftUI Container API

2026-04-01T10:08:32Z

For my personal RSS reader app I wanted to match the look and feel of Reeder Classic. This turned out to be not a trivial task as the customization possibilities especially for the List component are quite restricted. Fortunately Apple did provide us with some API to mitigate this, in the form of custom SwiftUI containers.

Previously, the only option available was to use collections of a specific data type and a @ViewBuilder closure. Now with the latest additions, SwiftUI offers new initializers for ForEach and Group that provide greater flexibility:

extension ForEach {
    public init<V>(subviews view: V, @ViewBuilder content: @escaping (Subview) -> Content) where Data == ForEachSubviewCollection<Content>, ID == Subview.ID, Content : View, V : View
}

extension ForEach {
    public init<V>(sections view: V, @ViewBuilder content: @escaping (SectionConfiguration) -> Content) where Data == ForEachSectionCollection<Content>, ID == SectionConfiguration.ID, Content : View, V : View
}

extension Group {
    public init<V>(subviews view: V, @ViewBuilder transform: @escaping (SubviewsCollection) -> Result) where Content == GroupElementsOfContent<Base, Result>, Base : View, Result : View
}

extension Group {
    public init<Base, Result>(sections view: Base, @ViewBuilder transform: @escaping (SectionCollection) -> Result) where Content == GroupSectionsOfContent<Base, Result>, Base : View, Result : View
}

So lets create our custom List component around these new APIs:

struct DSList<Content: View>: View {
    @Environment(\.theme) private var theme
    private let content: Content

    init(
        @ViewBuilder content: () -> Content
    ) {
        self.content = content()
    }

    var body: some View {
        ScrollView {
            LazyVStack(alignment: .leading, spacing: theme.tokens.spacing.l) {
                ForEach(sections: content) { section in
                    ThemedSection {
                        section.content
                    } header: {
                        section.header
                    } footer: {
                        section.footer
                    }
                }
            }
            .padding(.horizontal, theme.tokens.spacing.m)
            .padding(.vertical, theme.tokens.spacing.m)
        }
        .scrollBounceBehavior(.always)
        .background(.bg.primary, ignoresSafeAreaEdges: .all)
    }
}

Here you can see the new ForEach(sections:) API in practice. It allows us to extract and manage subviews grouped by Section.

Lets zoom into the implementation of ThemedSection to understand the whole layout:

struct ThemedSection<Content: View, Header: View, Footer: View>: View {
    @Environment(\.theme) private var theme
    @State private var cardStyle: DSSectionCardStyle = .card

    private let content: Content
    private let header: Header
    private let footer: Footer

    init(
        @ViewBuilder content: () -> Content,
        @ViewBuilder header: () -> Header,
        @ViewBuilder footer: () -> Footer
    ) {
        self.content = content()
        self.header = header()
        self.footer = footer()
    }

    var body: some View {
        VStack(alignment: .leading, spacing: theme.tokens.spacing.s) {
            header
                .font(theme.tokens.font.text.headline)
                .foregroundStyle(.text.muted)
                .textCase(.uppercase)

            cardContent

            footer
                .font(theme.tokens.font.text.description)
                .foregroundStyle(.text.muted)
        }
        .onPreferenceChange(DSSectionCardStylePreference.self) { style in
            cardStyle = style
        }
    }
    
    @ViewBuilder
    private var cardContent: some View {
        switch cardStyle {
        case .card:
            ThemedCardContent(content: content)
                .background(.bg.surface)
                .clipShape(
                    RoundedRectangle(
                        cornerRadius: theme.tokens.radius.m,
                        style: .continuous
                    )
                )
        case .transparent:
            ThemedCardContent(content: content)
        }
    }
}

extension ThemedSection where Header == EmptyView, Footer == EmptyView {
    init(@ViewBuilder content: () -> Content) {
        self.init(content: content, header: { EmptyView() }, footer: { EmptyView() })
    }
}

extension ThemedSection where Footer == EmptyView {
    init(
        @ViewBuilder content: () -> Content,
        @ViewBuilder header: () -> Header
    ) {
        self.init(content: content, header: header, footer: { EmptyView() })
    }
}

extension ThemedSection where Header == EmptyView {
    init(
        @ViewBuilder content: () -> Content,
        @ViewBuilder footer: () -> Footer
    ) {
        self.init(content: content, header: { EmptyView() }, footer: footer)
    }
}

struct ThemedCardContent<Content: View>: View {
    @Environment(\.theme) private var theme
    let content: Content

    var body: some View {
        Group(subviews: content) { subviews in
            let rows = Array(subviews)
            VStack(spacing: 0) {
                ForEach(0..<rows.count, id: \.self) { index in
                    subviews[index]

                    let isLast = index == subviews.count - 1
                    let suppressed = subviews[index]
                        .containerValues
                        .dsSuppressTrailingDivider

                    if !isLast && !suppressed {
                        Divider()
                            .foregroundStyle(.border.subtle)
                            .padding(.leading, theme.tokens.spacing.m)
                    }
                }
            }
        }
    }
}

Again we make use of the new API this time Group(subviews:). With this new API we can iterate over each subview inside a given section. You might have noticed another new addition in this implementation: Container Values.

SwiftUI introduces ContainerValues, a powerful tool for creating container-specific modifiers. Unlike EnvironmentValues or Preferences, ContainerValues are accessible only by the direct container, making them ideal for container-specific customizations.

By default our new custom list component will draw a separator for every row unless its the last row. However in my implementation I want the possibility to suppress the drawing of the Divider and I can do so by leveraging the new Container Values API:

extension ContainerValues {
    @Entry var dsSuppressTrailingDivider: Bool = false
}

struct DSListItem: View {
	var body: some View {
		Button {
			// ...
		}
		.containerValue(\.dsSuppressTrailingDivider, true)
        .buttonStyle(.listItem)
        .dsSectionCardStyle(.transparent)
	}
}

We now have a custom list component which renders a list using ScrollView and LazyVStack with arbitrary content. We can customize the look and feel however we like. We also can set specific behaviour through Container Values and the API looks very "SwiftUI-y":

DSList {
    Section {
        DSListItem(action: {}) {
            HStack {
                Text("Unread")
                    .font(.headline)
                Spacer()
                Text("20")
                    .font(theme.tokens.font.text.default)
                    .foregroundStyle(.secondary)
            }
            .font(theme.tokens.font.button)
            .foregroundStyle(.text.primary, .text.secondary)
        }
    } header: {
        Text("Folders")
    }
    
    // ...
}

Do you also already worked with this rather new API? What do you think is missing? Let me know.

If you are curious how this component looks in action head over to my article Building an iOS RSS reader which provides a short demo video showcasing it.

Adaptive Theming in SwiftUI

2026-04-01T09:45:18Z

One key aspect of my new personal RSS reader application is its dynamic theming capability. When I saw the themes Current provides I knew I wanted something similar for my own personal project.

Fortunately SwiftUI comes with a variety of APIs which make this possible to achieve in a clean way. A few requirements up front:

Themes should switch dynamically
Themes should be available in a light and dark variant
Variants of a theme should switch based on the user preferred color scheme
I want easy access to the theme primitives in the code

Lets start with the data model for the theme:

struct Theme: Hashable {
    let name: String
    let description: ThemeDescription
    let tokens: UiTokens
    
    init(name: String, description: ThemeDescription, tokens: UiTokens) {
        self.name = name
        self.description = description
        self.tokens = tokens
    }
    
    static let paper: Theme = .init(
        name: "Paper",
        description: .init(
            light: NSLocalizedString("Warm parchment tones inspired by printed books. The default palette, perfect for a cozy, literary reading experience.", comment: ""),
            dark: NSLocalizedString("Warm charcoal with amber accents, like reading by candlelight. Ideal for evening reading sessions.", comment: "")
        ),
        tokens: .init(
            color: .init(
                bg: .init(
                    primary: .init(light: Color(hex: "#FAF8F5")!, dark: Color(hex: "#1C1915")!),
                    // ...
                ),
                // ...
            )
        )
    )
}

struct ThemeDescription: Hashable {
    let light: String
    let dark: String

    func resolved(for colorScheme: ColorScheme) -> String {
        colorScheme == .dark ? dark : light
    }
}

struct UiTokens: Hashable {
    let color: ColorToken
    // ...
}

struct ColorToken: Hashable {
    let bg: Background
    // ...
    
    struct Background: Hashable {
        let primary: ThemeAdaptiveStyle<Color>
        // ...
    }
}
// ...

Looking at this model you might notice the usage of ThemeAdaptiveStyle so what is this exactly? It's my wrapper struct to a light and a dark variant for a given color token:

struct ThemeAdaptiveStyle<Style: Sendable & Hashable>: Sendable, Hashable {
    let light: Style
    let dark: Style
}

extension ThemeAdaptiveStyle {
    func resolved(for colorScheme: ColorScheme) -> Style {
        colorScheme == .dark ? dark : light
    }
}

With this in place I can then proceed to create a custom SwiftUI ShapeStyle:

struct BgShapeStyle: ShapeStyle {
    nonisolated(unsafe) let keyPath: KeyPath<Theme, ThemeAdaptiveStyle<Color>>

    func resolve(in environment: EnvironmentValues) -> some ShapeStyle {
        environment.theme[keyPath: keyPath].resolved(for: environment.colorScheme)
    }
}

To make this available we need an extension on ShapeStyle:

struct BgNamespace {
    var primary: BgShapeStyle { .init(keyPath: \.tokens.color.bg.primary) }
// ...
}

extension ShapeStyle where Self == BgShapeStyle {
    static var bg: BgNamespace { .init() }
}

Now we are able to set the primary background color via .background(.bg.primary) and it will automatically adapt to the light or dark variant thanks to the resolving of the environment color scheme in the custom shape style.

This won't compile currently as the custom shape style uses environment.theme to access the currently selected theme so lets add this key:

extension EnvironmentValues {
    @Entry var theme = Theme.paper
}

Everything thats left is to a) persist the selected theme and color scheme and b) provide a way to set this for the user:

@MainActor final class AppSettings: ObservableObject {
    private static let defaultTheme: Theme = .paper

    @Published var theme: Theme = defaultTheme
    @AppStorage private var themeName: String
    @AppStorage var colorScheme: ColorScheme?

    init(store: UserDefaults = .standard) {
        _themeName = AppStorage(wrappedValue: Self.defaultTheme.name, "themeName", store: store)
        _colorScheme = AppStorage("colorScheme", store: store)

        theme = Theme.allCases.first { $0.name == themeName } ?? Self.defaultTheme
    }
    
    func setTheme(_ theme: Theme) {
        self.theme = theme
        self.themeName = theme.name
    }
}

// NOTE: This allows @AppStorage to store an optional ColorScheme
extension ColorScheme: @retroactive RawRepresentable {
    public init?(rawValue: Int) {
        guard let userInterfaceStyle = UIUserInterfaceStyle(rawValue: rawValue),
              userInterfaceStyle != .unspecified,
              let colorScheme = ColorScheme(userInterfaceStyle)
        else {
            return nil
        }

        self = colorScheme
    }
    
    public var rawValue: Int {
        let userInterfaceStyle = UIUserInterfaceStyle(self)
        return userInterfaceStyle.rawValue
    }
}

With the theme and the color scheme stored in the UserDefaults we can use this new AppSettings class to store and retrieve the persisted values. I created a custom binding for this:

private var selectedTheme: Binding<Theme> {
    .init {
        appSettings.theme
    } set: { theme in
        appSettings.setTheme(theme)
    }
}

Make sure to set the environment variables as early as possible to the persisted ones in your application:

@StateObject private var appSettings: AppSettings = .live
@Environment(\.colorScheme) private var colorScheme
    
.environment(\.theme, appSettings.theme)
.preferredColorScheme(appSettings.colorScheme ?? colorScheme)
.tint(appSettings.theme.tokens.color.text.accent.resolved(for: colorScheme))

The ?? colorScheme is needed in case the colorScheme is nil when we want to apply the system/automatic color scheme mode. Make sure to also apply this to opened sheets as they sometimes do not update correctly otherwise.

This is quite a lot of code but ultimately we have a dynamic theming system at hand which we can easily extend and which adapts to the users preferences. Using our theme constants couldn't be easier as it works exactly like builtin SwiftUI shape styles.

If you are curious how this theming solution looks like in practice head over to my article Building an iOS RSS reader which provides a short demo video showcasing the theming in action.

Building an iOS RSS reader

2026-04-01T08:52:08Z

I felt the urge to build my own RSS reader for quite a while. However a lot of perfectly valid options exist, especially for iOS in my opinion.

For example NetNewsWire is a great piece of software and even better it's open source! Until now, I've been an avid user of the Reeder Classic. Two features, in particular, made it difficult for me to switch to any other client:

Navigation/User Experience: I think Reeder truly excels in this regard.
Instapaper integration: For my read-it-later needs I used Instapaper. Having my saved articles in the same application and enjoying the same reading experience as my RSS feeds was very important for me.

So why would I start and build my own client? As part of my ongoing effort to replace hosted services with my own self-hosted alternatives I decided to migrate all my saved articles from Instapaper to Readeck. Unfortunately no client exists yet which can both display RSS feeds as well as my saved articles from Readeck. Of course I could consume Readeck articles via a RSS feed but then I would not be able to mark them as read easily. Because of this and because I thought it would be a fun challenge I fired up Xcode and started a new project.

The current version is usable for my needs though it feels a bit rough around the edges. In terms of design and user experience I stayed close to the choices made by Reeder Classic and I incorporated the themes from the new cool kid on the block (Current). Please note this is a purely personal project. Yes I borrowed most of the themes from this application but I have no intention to ever release it publicly. It’s meant solely for my personal use. The combination of supported services (Miniflux and Readeck) means it probably wouldn’t attract many customers regardless.

In the upcoming posts I will share some of the challenges I faced building this application with SwiftUI and some interesting things I learned along the way. For now, all that’s left is to share a short demo video:

Proxmox Disaster Recovery

2026-04-01T08:35:35Z

I wrote about the newest addition to my homelab with the purchase of the JetKVM. I set things up and everything seemed to be working just fine but I always like to practice for an emergency when it comes to backups or data recovery. When an issue arrises I want to know what I am doing and that things will work. So here is a quick rundown of how I tested accessing my Proxmox VE host when for example after a kernel update or after changes to the GRUB bootloader the web UI/ssh won't be accessible:

Boot with Proxmox ISO through the JetKVM and its Virtual Media feature
In the installer select Advanced Options > Install Proxmox VE (Debug Mode)

In the console

Now with the installer started in Debug Mode a console is available which we can use:

exit
/sbin/modprobe zfs # load zfs
mkdir /RESCUE # create mount point
zpool import -f -R  /RESCUE rpool

Please note this is specific to my ZFS pool setup and might differ for you if you either do not use ZFS or have a different pool name in your installation.

Now make the necessary changes in the directory /RESCUE to fix the installation.
Then start Proxmox again via:

cd /
zpool export rpool
reboot

Lets just hope I will never need this for my production server but when I do I will be more than happy to have tested it works as expected.

Moving away from GitHub

2026-03-31T08:16:59Z

As part of my ongoing effort to gain more digital independence I decided to move away all my code from GitHub earlier this year. Up until then I was heavily invested in using GitHub but the shift towards AI scanning my code and the outages of the service with increasing frequency were the last straw that break's the camels back.

Migrating the repositories

No migration without a good plan. So I started to look what I would need to move over first. The repositories were pretty straightforward. I created a simple little script that would do the following:

Get all private and public repositories via the GitHub CLI.
Use the Forgejo API (/api/repos/migrate) to migrate each of the repos
Delete the repository on GitHub via the GitHub CLI

However this simple migrating left one thing to be missed: my blog. Previously I was using GitHub Pages to host my blog. Of course using GitHub pages is a totally valid option but I wanted to migrate everything and therefore looked for alternatives. I found the Codeberg Pages offering but at the time of my migration this was not very stable and I wasn't so sure whether I should rely on it. Instead I opted for just hosting it by my own.

Migrating GitHub Pages to nginx

To keep things simple I used nginx with certbot for SSL certificate renewal as I already knew these tools and did not want to invest any further time into looking at alternatives like Caddy. In the end this is a very low volume static website and nginx will handle it totally fine. Since this post is about the migration to Forgejo I won't go much into detail here but I basically installed certbot and nginx, setup certbot with a cron job to automatically renew my certificate via LetsEncrypt and configured nginx with a basic HTTPS only configuration to serve a folder of static html files.

With automatic certificate renewing, the webserver and the firewall in place I could already upload a simple test HTML file and it worked flawlessly. However one key component was still missing: Deploying the actual blog.

Deploying the blog via Forgejo CI

One thing that I always liked about using GitHub Pages was the integration with GitHub actions to automatically deploy my blog whenever I make any changes. I use a custom static site generator I build in the programming language Swift which turns markdown files I write into the HTML you can see when browsing this very blog.

Since Forgejo Workflows are more or less compatible with GitHub actions creating the actual workflow configuration was pretty straightforward.

# .forgejo/workflows/deploy.yml
on:
  push:
    branches:
      - main

enable-email-notifications: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
        - name: Checkout 🛎️
          uses: actions/checkout@v4 # https://code.forgejo.org/actions/checkout@v4
        
        - uses: actions/setup-swift@v2 # https://github.com/swift-actions/setup-swift@v2
          with:
            swift-version: "6.2"
          name: Setup Swift
       
        - name: Get Swift version
          run: swift --version
        
        - name: Build Site 🔧
          run: swift run
          shell: sh
      
        - name: Verify build output
          run: ls -la Site/
          shell: sh

        - name: Install rsync
          run: |
            apt-get update
            apt-get -yq install rsync
          shell: sh
      
        - name: Deploy via rsync
          run: |
            mkdir -p ~/.ssh
            echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
            chmod 600 ~/.ssh/id_rsa
            rsync -avz -vv --progress --delete -e "ssh -p ${{ secrets.REMOTE_PORT }} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null" Site/ ${{ secrets.REMOTE_USER }}@${{ secrets.REMOTE_HOST }}:${{ secrets.REMOTE_PATH }}
          shell: sh

The workflow builds the site with the Swift compiler and then writes the output via rsync to my web server. I had some issues getting the forgejo runner setup correctly especially finding and hosting the correct docker image for the runner (ubuntu-latest in this example configuration). Eventually I figured it out and then went one step ahead and replaced the actions above from pointing to remote URLs to my own actions repository. To consume these actions without the need to specify the host I updated my forgejo app instance configuration with the following:

# gitea/conf/app.ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://mydomain.tld

This way I keep full control of what is running in my CI and am again a bit more independent in this whole process.

Let me know whether you recently did something similar. Did you encounter any issues? Do you have any questions regarding further details about the migration process? I am happy to hear from you.