wal.sh
home > research > org-graphviz-publish-workflow · Jun 21, 2026
org-modegraphvizdotob-dotorg-publishdiagramsTRAMPliterate programming

Org-Mode Graphviz Publish Workflow

Table of Contents

1. The invariant

Diagrams in this site live as inline #+begin_src dot blocks inside org files. The only on-disk artifact is the generated PNG. There are no loose .dot files under site/.

The pipeline:

  1. Write the dot source inline in the org file
  2. Execute via ob-dot (Emacs org-babel) to generate the PNG
  3. Publish the HTML via org-publish + TRAMP to the remote server
  4. Deploy the PNG via rsync (gmake deploy-diagrams)

Delete the PNG, re-run the pipeline, and the diagram reappears. This note is a test of that invariant.

2. Example: a three-stage pipeline

The diagram below shows the publish pipeline itself: org source produces HTML and PNG, which are deployed to the server via two independent paths.

diagram-publish-pipeline.png

3. Header anatomy

Every dot block in this site follows this pattern: 

#+begin_src dot :file <name>.png :tangle <name>.dot :cmdline -Tpng :exports results
digraph { ... }
#+end_src
Header Purpose
:file <name>.png Output path for the compiled PNG (org-babel writes here)
:tangle <name>.dot Tangle target for the raw dot source (for audit)
:cmdline -Tpng Passed to the dot command (output format)
:exports results Show only the PNG in HTML export (not the source)

To show both the source and the image, use :exports both.

4. gmake targets

# Rebuild all diagrams (92 files, dot blocks only)
gmake diagrams

# Deploy PNGs to production (research + events)
gmake deploy-diagrams

# Full deploy (includes diagrams + publish + sitemap + extras)
gmake deploy

# Single-file publish (fast path, ~30s)
gmake publish-file FILE=site/research/org-graphviz-publish-workflow/index.org

5. Verification: delete and rebuild

The round-trip test: 

# 1. Delete the PNG
rm site/research/org-graphviz-publish-workflow/diagram-publish-pipeline.png

# 2. Rebuild via regen-diagrams.el
emacs --batch -l org -l elisp/regen-diagrams.el \
  site/research/org-graphviz-publish-workflow/index.org

# 3. Verify regenerated
ls -la site/research/org-graphviz-publish-workflow/diagram-publish-pipeline.png

# 4. Publish + deploy
gmake publish-file FILE=site/research/org-graphviz-publish-workflow/index.org
gmake deploy-diagrams

# 5. Verify production
curl -sI https://wal.sh/research/org-graphviz-publish-workflow/diagram-publish-pipeline.png

6. Related