Synapse separates the application from everything the application says. One repository holds the code; a growing set of others hold the writing, and the platform merges them into a single catalog at runtime. Publishing a lesson is a git push to whichever repository owns it, and nothing is rebuilt.

This is the working guide. It assumes nothing beyond a terminal and covers the whole path — cloning, running the stack, writing a lesson with every feature the renderer has, verifying it, and getting it live. Where something fails quietly, this guide says so, because a wrong fence does not throw an error; it just renders as a plain code block and leaves you wondering.

Revised August 2026: content now spans several repositories rather than one, plain code fences open in a full editor, and there are two in-app diagram editors. Those sections are new; everything else stands.

One Catalog, Many Repositories

The application reads content off disk at a path it is given. In production that path is a checkout maintained by a git-sync sidecar; in development it is wherever you cloned the content repository. Neither the server nor the browser can write to it.

Spine and satellites

The spine is mounted first and always. Everything a satellite cannot own alone lives there: the blog and the category list that groups books on the library page.

A satellite is a repository whose root is a book — a book.json beside numbered chapter directories, with no wrapper folder. It is registered once from /admin, and from then on the server fetches it as a GitHub tarball on a sixty-second loop. The registration row owns where the book sits and in what order; book.json owns the slug, because the slug is the URL.

Six books are satellites today — dsa, java, low-level-design, python, sql and system-design-from-first-principles. Nothing about writing a lesson changes when a book moves: the fences, the frontmatter and the URL rules below are identical in the spine and in a satellite.

The practical consequences are worth internalising before you start:

Running It Locally

You do not need to be a developer to do this. You need to copy six commands into a black window and wait. Everything below is written for someone who has never opened a terminal.

If you only want to write — fix a typo, add a lesson — you can skip this entire section twice over. Contributors edit lessons inside the app itself, with no installation at all, and writers who prefer files need only the content folder and a text editor. Running the whole platform is for people who want to change the software.

Step 0 · Open a terminal

The terminal is a window where you type commands instead of clicking. Everything below gets pasted into it, one block at a time, pressing Enter after each.

A line starting with # in the blocks below is a comment for you, not a command — you can paste it along with everything else and the computer will ignore it.

Step 1 · Install the four tools

Pick your operating system and paste the block. Each installer prints a lot of text — that is normal. Wait for your prompt to come back before pasting the next thing.

On a Mac

# 1. Homebrew — the standard Mac installer for developer tools.
#    Skip this line if `brew --version` already prints something.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 
# 2. Git and Node (22 or newer).
brew install git node
 
# 3. Rust, from the official installer. Choose option 1 (default) when it asks.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
 
# 4. Docker Desktop — this one has a normal installer window.
brew install --cask docker-desktop

Then open Docker Desktop from your Applications folder once and leave it running. Docker only works while that app is open; its whale icon sits in the menu bar at the top of the screen.

On Windows (inside Ubuntu/WSL) or on Linux

# 1. Git, curl and build tools.
sudo apt update && sudo apt install -y git curl build-essential
 
# 2. Node 22.
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
 
# 3. Rust. Choose option 1 (default) when it asks.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
 
# 4. Docker.
sudo apt install -y docker.io docker-compose-v2
sudo usermod -aG docker $USER      # lets you use docker without typing sudo

On plain Linux, close the terminal and open a new one after that last line, or the permission change will not have taken effect. On Windows, install Docker Desktop for Windows instead of the apt step above and enable Settings → Resources → WSL integration for your Ubuntu — then Docker works from inside Ubuntu automatically.

Check it worked. Paste this; you want four version numbers and no "command not found":

git --version && node --version && cargo --version && docker --version

Step 2 · Download the two folders

# Make a working folder and move into it.
mkdir -p ~/synapse-workspace && cd ~/synapse-workspace
 
# The application, then the writing.
git clone https://github.com/ani2fun/synapse.git
git clone https://github.com/ani2fun/synapse-content.git

Keep them side by side like that. The application looks for the writing in a folder next to it, so this layout works with no configuration. (~ means your home folder; on a Mac that is /Users/yourname.)

Two folders is all you need to run the platform. The spine is the only content repository a local stack mounts by default — satellites are fetched over the network from their registration, which a development machine has no reason to do. If you want a satellite in your local catalog, clone it beside the others and point SYNAPSE_LOCAL_SOURCES at it; the registry itself cannot hold a local path.

Step 3 · Start the four helper services

Docker downloads and runs these for you. The first time takes a few minutes because it is fetching them; afterwards it is seconds.

cd ~/synapse-workspace/synapse
docker compose up -d db go-judge keycloak

-d means "in the background". To check they are alive:

docker compose ps

Step 4 · Start Synapse

cd ~/synapse-workspace/synapse
dev-tools/dev

The first run compiles the server and takes several minutes — anywhere from two to ten depending on your machine. It looks like it has frozen. It has not; Rust is simply slow to build the first time and fast forever after. Later runs start in seconds.

Leave this window open — the site runs for as long as it does. Press Ctrl + C in it to stop everything.

Step 5 · Open it

Go to http://localhost:5373 in your browser. You should see the library, with every book in your content folder.

To sign in — needed only for running code and saving solutions — use username tester, password tester.

Step 6 · Change something and watch it appear

This is the moment the two-repository split pays off. With the site still running, open any lesson file in the other folder — say ~/synapse-workspace/synapse-content/blog/working-with-synapse.md — in any text editor, change a word, and save.

Now refresh the page in your browser. Your change is there. No rebuild, no restart, no publish button. The server re-reads the content folder on every request, so writing feels like editing a document rather than deploying software.

When something goes wrong

If your two folders are not siblings, tell the server where the writing is:

SYNAPSE_ROOT=/full/path/to/synapse-content dev-tools/dev

And to check the server is answering at all, this should print {"status":"ok"}:

curl -s localhost:8280/api/health

The settings worth knowing

Everything is configured by environment variables with working defaults, so you can ignore all of them until you want one. Set them in front of the start command, as in the SYNAPSE_ROOT example above.

The Content Model

A directory becomes a book the moment it contains a book.json. Everything else follows from the filesystem.

synapse-content/
  my-book/
    book.json                       ← this file is what makes it a book
    index.md                        ← the syllabus page, listed first
    01-foundations/                 ← a chapter (nestable, up to 6 deep)
      01-first-lesson.md
      02-second-lesson.md
      03-a-problem.md
      03-a-problem.editorial.md     ← worked solution, revealed on demand
      03-a-problem.tests.json       ← the judge's suite
  _media/my-book/first-lesson/…     ← images and video, at the REPO ROOT
  local-only/                       ← never published

{
  "title": "My Book",
  "description": "One paragraph, shown on the library card.",
  "tags": ["architecture"],
  "estimatedReadingMinutes": 180,
  "order": 3,
  "slug": "my-book"
}

Three rules that decide your URLs

Lesson frontmatter

---
title: "Consistent Hashing"
summary: "One line, shown wherever the lesson is listed."
essential: true
---

title and summary are required. essential: false marks an optional deep-cut. One more field changes the lesson's kind:

kind: problem

That single line switches on the two-pane workbench, unlocks the .editorial.md sidecar and loads .tests.json. Without it, both sidecars are silently ignored — which is the most common reason a problem page renders as ordinary prose.

The Fence Vocabulary

This is what separates Synapse from a static site generator. Seven language names are reserved — the renderer claims them for widgets instead of syntax-highlighting them:

mermaid · d2 · viz · quiz · problem · testcases · editorial

Everything else is a display language, and what it does is decided by the fence's meta — the text after the language name.

Runnable code, live

Eleven languages run in the sandbox: Python, Java, Scala, C, C++, Go, Rust, Kotlin, TypeScript, JavaScript and SQL. Add the bare word run to a fence and the reader gets an editor and a ▶ button.

Here is one, in this post — blog posts cross the identical pipeline a lesson does, so every feature described here works here too. Press ▶:

Plain fences are runnable too — Try in Editor

run is not the only way a reader reaches the sandbox. Any plain fence in a language the sandbox speaks grows a Try in Editor button in its toolbar, which opens the snippet in a near-fullscreen editor with its own Run button and a standard-input box. You write nothing extra: no run, no meta, no change to the Markdown at all. A prose fence in a language the sandbox does not speak — bash, json, yaml — still gets the toolbar and the copy button, just not this one.

The distinction worth keeping straight when you write:

Editing in the popup requires signing in; running does not. A signed-in reader's edits are kept in their own browser, so closing the editor and opening the same snippet again — or coming back to the lesson tomorrow — returns the version they were working on rather than your original. Reset to the original puts your fence back, and rewriting that fence retires their saved copy automatically, so a reader is never handed edits that no longer fit the code around them.

Adjacent fences group

Two run fences in different languages, written back to back, become one card with a language switcher — not two cards:

```python run
def solve(): ...
```
 
```java run
class Main { }
```

The same grouping applies to solution fences and to plain display fences, which become tab groups. If you want two separate cards, put a sentence between them.

Quizzes

A quiz fence carries one JSON object:

{"prompt": "Which of these never reaches the origin?", "options": ["A cache hit at the edge", "A submission", "A code run"], "answer": "A cache hit at the edge"}

Written as a ```quiz fence, that renders as an interactive question. Here is a real one:

answer must match one of the options exactly, by string equality. A mismatch produces a question nobody can answer correctly, and nothing warns you.

Visualisation

The feature the platform exists for: watch your own code execute, step by step, with the data structure drawn.

Add a viz= hint to a run fence and the traced execution becomes a picture:

```python run viz=array:nums
```

The part after the colon is the root — the variable the picture is about. A heap contains many objects; naming the root is what makes the drawing about nums rather than about whichever object the tracer happened to see first.

Seventeen structures are available, and the spelling is exact:

array · grid · stack · queue · deque · tree · heap · list · hashmap
graph · trie · union-find · fenwick · bitset · skiplist · segment-tree · callstack

Two of them are kebab-case, and they are the two everyone gets wrong: union-find and segment-tree. Write unionFind and the fence parses to nothing, renders as a plain code block, and tells you nothing. Tracing currently follows Python and Java.

Judged Problems

A problem is a lesson with kind: problem and up to two sidecars sharing its stem:

That last row is the important one. The suite is read twice by two different consumers: the reader's page is given only the cases marked as samples, while the judge — server-side — gets the whole thing. A suite can hold thirty cases and show three. The hidden ones are not hidden by the interface; they are never serialised into the response at all.

A malformed suite is a loud error on both paths rather than a silently empty one, because a problem that quietly grades against nothing is worse than a problem that fails to load.

What happens when a reader submits

Submitting requires signing in, and — in deployments that enforce it — being on a submit allowlist, because a saved submission spends shared compute and storage. Running code needs neither; anonymous readers are rate-limited per IP, signed-in ones per account with a larger budget.

Diagrams and Walkthroughs

Two engines, and they are not interchangeable.

Here is a Mermaid diagram of the flow this whole post describes:

Drawing one without leaving the site

You do not have to write diagram source blind and refresh to see it. Synapse ships two editors — /d2 and /mermaid — each a split view with the source on the left and the live figure on the right, autosaving as you type.

They are also the fastest route from a sketch to a lesson. Open one on a blank page and it is a scratchpad; open it on an existing figure and it loads the published source, so you can fix a diagram in place. Either way the Add to lesson button routes the result through the same review-and-pull-request pipeline as any other content edit — there is no separate publishing path and no endpoint of their own.

Two details worth knowing before you reach for one:

Walkthroughs, and the one rule you must not break

An architecture diagram is a d2 fence like every other figure — no model file, no shared workspace, no service. What makes it a walkthrough is the boards marker, which turns one source into a tree of boards the reader clicks down through: a system, its containers, the code inside one of them.

```d2 boards name="c4-payments" root="System Context"
sys: "Payments\n[Software System]" { link: layers.container }
 
layers: {
  container: {
    api: "Payment API\n[Go service]" { link: _.layers.code }
  }
  code: {
    guard: "IdempotencyGuard"
  }
}
```

Everything else about it is ordinary. A walkthrough is addressed by the hash of its source, so the same one in two lessons is one set of boards; name= is a label for the editor and the export, not a path. Nothing is gathered from other repositories, so a satellite's diagrams work the day the satellite is registered — there is no build to deploy first, and no shared namespace to collide in.

Write the boxes up as prose underneath the figure. Text a reader has to click for is text that search, the sitemap, and most readers never see.

Media, Blog Posts and Links

Media lives at the repository root

Not beside the lesson. One _media/ tree, addressed by book and lesson slug:

_media/my-book/consistent-hashing/ring.svg

![The hash ring](/media/my-book/consistent-hashing/ring.svg)

SVG, PNG, WebP, JPEG, GIF, MP4 and WebM are served, range-aware, with one shared hour of cache — media is path-addressed rather than content-hashed, because authors replace files in place.

Links are not rewritten

The renderer does not touch your links, so intra-site links must be app-absolute and built from slugs:

Only link to lessons that already exist. Nothing validates this for you, so a link-check before publishing is worth the thirty seconds.

Blog posts

A blog post is a Markdown file in blog/. The slug is the filename; a leading _ marks it a draft and it is skipped entirely.

---
title: A Post
summary: One or two sentences for the listing.
publishedAt: 2026-07-23
tags: [engineering]
readMinutes: 8
eyebrow: Optional · Kicker · Line
meta: Read Time=8 min; Anything=You Like
---

Posts cross the identical markdown pipeline lessons do — the runnable fence, the quiz and the diagram above are all proof of it — plus a rich block vocabulary of heroes, callouts, comparison tables and pull-quotes that this post is built from. Read one of the existing posts' source as the reference; the classes are all blog-post__*.

Editing Without git

There is a second way to change a lesson, added for people who should not have to learn git to fix a typo.

Five things worth knowing before relying on it:

• Existing .md lessons only. No sidecars, no book.json, no new files, no media uploads.
• A book can move mid-review. A new suggestion is routed by wherever the lesson resolves now; a revision to one already under review goes back to the repository recorded on it when it was opened, so an in-flight pull request cannot be stranded by a split.
• A second edit while your pull request is open adds a commit to the same branch, rather than opening a second one — so a reviewer gets one conversation per page.
• The frontmatter fence is part of what you are editing. Deleting it is refused, because it silently changes the page's title, summary and social tags. So is submitting a file with no title left.
• If the file changed on disk while you had it open, submitting is a 409 and you are asked to reload and reapply. There is no lock; a fingerprint comparison is the guard.

Locally this runs in dry-run by default: the entire flow executes — the allowlist gate, the drift guard, the validation, the branch derivation, the stored history — and only the final call to GitHub is skipped. You can exercise the whole feature without a credential anywhere near your machine.

Verify Before You Push

Content has no compiler, so the checks are yours to run. In rough order of how often they catch something:

If you are changing the application rather than the content, the gates are automated and worth running before you push:

cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
dev-tools/check-conventions.sh      # layer purity + file-size caps
cd web && npx vitest run
dev-tools/e2e                       # browser suite + the per-page JS budget

That last one is the interesting gate. It fetches each page kind from a production-shaped serve and sums the gzipped weight of everything the HTML loads eagerly, failing the build over 250 KiB. The lazy parts — the editor, the diagram engines, the visualiser — are dynamic imports, so they cannot appear in that sum by construction rather than by an exclusion list somebody has to maintain.

How It Actually Ships

Two paths, two very different speeds, and knowing which one you are on tells you whether to wait or to investigate.

Prose, media and sidecars take the fast path. For the spine, a sidecar polls the content repository, fetches the new commit into its own directory, and atomically repoints a symlink. The application derives its content version from that checkout's git hash, re-read per request — so a new commit is a new version, a new cache key, and no redeploy. Well under a minute.

The symlink is doing real work there. Updating files in place would let a request landing mid-write see one lesson from the new commit and another from the old. A symlink swap is a single atomic operation: every request sees exactly one commit.

A satellite takes the same fast path by a different road: no sidecar and no checkout, just the server pulling the repository as a GitHub tarball into its content cache on a sixty-second loop. Same outcome — git push, wait under a minute, it is live — and the same absence of a rebuild.

Then there is the cache. Pages and content are served with max-age=60, stale-while-revalidate=600, so a reader may see the previous version for up to a minute — and, if their edge node has not revalidated, a stale-but-instant copy for longer while the fresh one is fetched behind them. That is a deliberate trade: for a learning platform, a one-minute delay on a typo fix is invisible, and never showing anyone a spinner is worth far more.

Traps That Fail Quietly

Every item here has actually happened. None of them produces an error message.

The Whole Thing in Ten Lines

Once the four tools from Step 1 are installed, this is the entire thing:

mkdir -p ~/synapse-workspace && cd ~/synapse-workspace
git clone https://github.com/ani2fun/synapse.git
git clone https://github.com/ani2fun/synapse-content.git
cd synapse
docker compose up -d db go-judge keycloak
docker compose exec db createdb -U synapse synapse_rs
dev-tools/dev                                  # → http://localhost:5373
 
# then, in the other folder:
#   mkdir my-book && write book.json
#   mkdir my-book/01-foundations
#   write my-book/01-foundations/01-first.md with title + summary frontmatter
#   refresh the page — it is already there

That last line is the part worth keeping. There is no build step between writing a lesson and reading it, and no build step between merging one and it being live. The whole authoring pipeline is a file, a commit, and a symlink — and every feature in this guide is something you get by typing a word after a triple backtick.