Entropy Exchange — Claude Code Instructions

Entropy Exchange is the Synaptiq tech blog, built with Quarto and deployed to GitHub Pages (public) and Cloudflare Pages (internal).

Quick Commands

just preview          # Local dev server with hot reload
just render           # Render with default profile
just render-public    # Render public site (drafts excluded)
just render-internal  # Render internal site (all content)
just post <slug>      # Scaffold a new blog post
just lint             # Run pre-commit hooks on all files
just status           # Show draft and playbook inventory
just clean            # Remove _site and _site-internal
just install          # Install deps + pre-commit hooks

Content Types

  • Blog posts — general audience, appear on the public site
  • Playbooks — internal technical guides, categorized with categories: [playbook]
  • Drafts — any post with draft: true in frontmatter

Post Formats

  • .qmd — Quarto Markdown (preferred for text-heavy posts)
  • .ipynb — Jupyter notebooks (for code-heavy / Databricks posts)

All posts live under posts/<slug>/index.qmd (or index.ipynb).

Frontmatter Conventions

---
title: "Post Title"
author: "Author Name"
date: "2025-01-15"
categories: [ai, llm]    # add "playbook" for internal playbooks
draft: true               # set false when ready to publish
---

Filter Pipeline

Quarto processes content through these filters in order:

  1. filters/filter.py — ipynb pre-filter that strips Databricks cell metadata
  2. filters/drafts.lua — generates the drafts index page
  3. filters/playbooks.lua — generates the playbooks index page

Execution & Freeze Behavior

  • _quarto.yml sets freeze: auto at project level
  • posts/_metadata.yml sets freeze: true for all posts
  • This means post outputs are frozen and won’t re-execute unless you explicitly delete _freeze/<post>/ first

Key Directories

posts/              # All blog posts (each in its own subdirectory)
filters/            # Lua and Python Quarto filters
static/css/         # Site CSS
static/images/      # Site-level images (post images go in their post dir)
_quarto.yml         # Main Quarto config
_quarto-public.yml  # Public profile overrides
_quarto-internal.yml # Internal profile overrides

Rules

  • Always set draft: true on new posts
  • Put post images in the post’s own directory, not in static/images/
  • Post-specific Python deps go in the post’s own pyproject.toml, not the root one
  • Don’t modify Lua filters without doing a full just render to verify
  • Don’t add dependencies to the root pyproject.toml unless they’re needed by filters or site build
  • Don’t commit large binary files — use .gitignore or external hosting