quartz-module/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository contains a single NixOS module (quartz.nix) that provides a service for hosting Quartz static sites. Quartz is a fast, batteries-included static site generator that transforms Markdown content into full featured websites.

Architecture

The module creates a complete deployment system:

1. Git-based content management - Clones and pulls content from a configurable git repository
2. Build service (quartz-pull-and-build.service) - Handles npm install and npx quartz build
3. Timer - Periodic rebuilds (default: every 15 minutes) as fallback
4. Webhook server (optional) - Listens for Forgejo/GitHub push events to trigger immediate rebuilds
5. nginx vhost - Serves the built static files with ACME/SSL

Key assumption: nginx and ACME must be configured elsewhere in the NixOS configuration.

Testing Changes

To test this module, include it in a NixOS configuration:

{ pkgs, ... }:
{
  imports = [ ./quartz.nix ];

  services.quartz = {
    enable = true;
    domain = "docs.example.com";
    gitRepo = "https://git.example.com/user/quartz-notes.git";
  };
}

Validate syntax with: nix-instantiate --parse quartz.nix