Entropy Exchange — Agent Reference

Entropy Exchange is the Synaptiq tech blog, built with Quarto and deployed to GitHub Pages (public) and Cloudflare Pages (internal). CI runs via GitHub Actions on push to main.

Prerequisites

Tool Purpose macOS install
Quarto ≥ 1.8 Static site generator brew install --cask quarto
uv Python package/project manager brew install uv
just Command runner (replaces Make) brew install just
Python 3.13+ Runtime (managed by uv) via uv
Ollama Local LLM inference (optional) brew install --cask ollama
Docker Integration tests (optional) brew install --cask docker

Bootstrap

git clone git@github.com:synaptiq/entropy-exchange.git && cd entropy-exchange
script/bootstrap   # installs Quarto, uv, just (uses Homebrew on both macOS and Linux)
just install       # uv sync + pre-commit install
just preview       # verify the site builds and opens in browser

Commands

just                  # List all available recipes
just bootstrap        # Install system prerequisites (Quarto, uv, just)
just install          # Install project deps + pre-commit hooks
just preview          # Local dev server with hot reload
just render           # Render site (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 clean-all        # Remove _site, _site-internal, and _freeze
just test             # Run Docker integration tests

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; visible on internal site only

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).

Creating a New Post

just post my-post-slug    # Creates posts/my-post-slug/index.qmd with draft frontmatter

Then edit the generated file. Preview with just preview.

Frontmatter Conventions

Every post must have:

---
title: "Descriptive Title"
author: "Author Name"
date: "YYYY-MM-DD"
categories: []
draft: true
---

Category Conventions

  • General topics: [ai, llm, ocr, data-engineering, mlops] etc.
  • Internal playbooks: include playbook in categories, e.g. [playbook, databricks]
  • Posts with playbook category appear on the playbooks index page

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)
test/                  # Docker integration tests
_quarto.yml            # Main Quarto config
_quarto-public.yml     # Public profile overrides
_quarto-internal.yml   # Internal profile overrides
posts/_metadata.yml    # Per-post metadata defaults (freeze: true)

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
  • Post outputs are frozen and won’t re-execute unless you explicitly delete _freeze/<post>/ first

Working with Notebooks

  • Databricks metadata is auto-cleaned by filters/filter.py
  • Each notebook post can have its own pyproject.toml for dependencies
  • The root pyproject.toml only covers site-build dependencies

Content Guidelines

  • Write for a technical audience familiar with ML/AI and data engineering
  • Don’t include passwords, API keys, internal URLs, or customer-specific details
  • Use relative paths for images stored in the post directory
  • Put post images in the post’s own directory, not in static/images/
  • Prefer .qmd for text-heavy content, .ipynb for code-heavy/notebook content

Things to Avoid

  • Don’t add dependencies to the root pyproject.toml (post deps go in post dirs)
  • Don’t modify Lua filters without running just render to verify
  • Don’t commit large binary files (images > 1 MB, datasets, model weights)
  • Don’t change posts/_metadata.yml freeze settings without good reason
  • Don’t remove draft: true without explicit approval

Verification Checklist

Before considering work complete:

  1. just lint — pre-commit hooks pass
  2. just render-public — public build succeeds (drafts excluded)
  3. just render-internal — internal build succeeds (all content included)
  4. just test — Docker integration tests pass (if Docker is available)