01 Oct 2026
\nWhy the writing stays inside Emacs
\nI’ve stumbled across a method of composing programs that excites me very much. In fact, my enthusiasm is so great that I must warn the reader to discount much of what I shall say as the ravings of a fanatic who thinks he has just seen a great light.
\nWelcome to the first Byzantine Systems blog post. This is not my\nfirst attempt at building a website around Org-mode. I have already\nwritten about the road to Emacs\nmaximalism\nin my own personal blog, where Emacs, a few questionable scripts and Nix\nheld everything together. This time I wanted to keep the part that\nworked (writing everything in Emacs) while making the publishing side\nsmaller, typed and easier to understand.
\nThe end experiment uses the following tools:
\nThe last two points look too overkill for a simple static page, but I'll let you jugde by way we create the page that lists all posts. It's just a Gleam function returning a Lustre element:
\nThe post index is ordinary, type-checked Gleam code.
\npub fn posts_page(posts: List(Post(msg))) -> Element(msg) {\n let sorted = list.sort(posts, fn(a, b) { timestamp.compare(b.date, a.date) })\n layout("Posts", [\n html.h2([], [html.text("Posts")]),\n case sorted {\n [] -> html.p([], [html.text("No posts yet.")])\n _ -> html.ul([], list.map(sorted, post_link))\n },\n ])\n}The tl;dr version of this blogpost looks like this:
\nOne important detail, that previous diagram was generated inside Emacs,\nI want to keep the idea of "diagrams as code" alive, and for now d2\nhas been serving me well. This is what the diagram code looks like\nwithout the Emacs magic to keep only the result (the image).
direction: right\nstyle.fill: "#ffffff"\n# Default node styling\n*.shape: rectangle\n*.style: {\n border-radius: 8\n stroke-width: 2\n font-size: 12\n}\n# Default edge styling\n(* -> *)[*].style: {\n stroke: "#64748b"\n font-color: "#475569"\n stroke-width: 2\n font-size: 10\n}\nemacs: "1. Emacs + Orgmode\\nWrite raw content (.org)" {\n style: {\n fill: "#f3e8ff"\n stroke: "#a855f7"\n font-color: "#581c87"\n }\n}\npandoc: "2. Pandoc + plugins\\nConvert Org to Markdown (.md)" {\n style: {\n fill: "#e0f2fe"\n stroke: "#0284c7"\n font-color: "#075985"\n }\n}\nblogatto: "3. Blogatto\\nGenerate final HTML" {\n style: {\n fill: "#dcfce7"\n stroke: "#16a34a"\n font-color: "#14532d"\n }\n}\nemacs -> pandoc: Export\npandoc -> blogatto: BuildModerately related, but my close friend Marcos\nMagueta made an interesting video called\nGNU Shepherd is the abstraction for a better computing\nage, there he argues about\nBLOAT, a word so despised in the UNIX world, but most people do so\nwithout:
\nEmacs, when taken from a UNIX philosophy perspective, is pure bloat.\nIndeed, Emacs does not follow UNIX's "do one thing well". One can even\nargue that is is actually good, the lack of unified environment ends up\ncausing userland BLOAT anyway. By this very definition, Emacs would\nbe good bloat.
\nConsistency requires a concentrated effort on the part of some central body that promulgates standards. Applications on the Macintosh are consistent because they follow a guidebook published by Apple. No such body has ever existed for Unix utilities. As a result, some utilities take their options preceded by a dash, some don’t. Some read standard input, some don’t. Some write standard output, some don’t. Some create files world writable, some don’t. Some report errors, some don’t. Some put a space between an option and a filename, some don’t.
\nAlso, leaving Emacs would be admiting defeat. Writing a blogpost (or notes) for me is more than just writing paragraphs. I like to put source code around, I sometimes like to export my notes to , I like having proper bibtex citations working at all times. If every one of those requires another application, the work becomes a tour of windows (or TUIs) which happen to contain fragments of the same idea. The long term goal is eventually moving everything inside Emacs, but that day is not today.
\n(…) trivial usage of Org-mode is nothing more than text editing, from which point the user can start to add special plain text Org-mode elements to the document. Org-mode is therefore easy to adopt and aims to be a general solution for authoring projects with mixed computational and natural languages. It supports multiple programming languages, export targets, and work flows.
\nWe already have Markdown, right? It is ubiquitous, readable and\nsupported by almost every static-site generator. Indeed, this site uses\nthe Markdown pandoc creates it and blogatto consumes it. I just do\nnot write it directly.
The reason being that Orgmode is a far superior format, whose only\ndownside is that you have to be inside Emacs to fully enjoy (and that\nseems like an okayish tradeoff). If you really want it, .org can stay\nas a simple lightweight markup format… or you can run arbitrary source\nblocks inside your org document, with custom command arguments and even\na place for the generated results.
That's what makes it really powerful, that's why I like to embed d2\ndiagrams inside my org notes in such a way that I can always re-generate\nimages/diagrams on demmand. It's a small reproducible (research-like)\nenvironment that is very similar to the famous Jupyter Notebooks.
Org-mode extends Emacs with a simple and powerful markup language that turns it into a language for creating, parsing, and interacting with hierarchically-organized text documents. Its rich feature set includes text structuring, project management, and a publishing system that can export to a variety of formats. Source code and data are located in active blocks, distinct from text sections, where "active" here means that code and data blocks can be evaluated to return their contents or their computational results. The results of code block evaluation can be written to a named data block in the document, where it can be referred to by other code blocks, any one of which can be written in a different computing language. In this way, an Org-mode buffer becomes a place where different computer languages communicate with one another. Like Emacs, Org-mode is extensible: support for new languages can be added by the user in a modular fashion through the definition of a small number of Emacs Lisp functions.
\nMarkdown can imitate pieces of this through extensions and external\ntools, but then the authoring model is the accidental intersection of a\nparticular parser, editor and plug-in collection. Org-mode's features\nbelong to the same coherent system. More importantly, they are\ninteractive in the editor instead of being instructions which only\nbecome meaningful after a build.
\nOne tempting approach would be to teach blogatto how to parse Org\ndirectly. I'll make sure to explore this in the long run and even push\nto the main repo. For now, pandoc already understands Org, already\nemits GitHub Flavored Markdown and already has a citation processor, so\nthe conversion stage can stay boring:
pandoc -s org/posts/example.org \\\n -t gfm \\\n --citeproc \\\n --bibliography=priv/bibtex/emacs.bib \\\n -o blog/posts/example/index.mdThe real command is assembled by src/convert.gleam. It finds every Org\npage and post, adds all the BibLaTeX databases under priv/bibtex and\nwrites the Markdown into the directory structure Blogatto expects.\nConverted files are build products and are ignored by Git. The org/\ndirectory is the only source of truth.
There are three small Lua filters for the cases where a generic conversion is not quite enough:
\nverse.lua preserves Org verse blocks as structured HTML;bibliography.lua keeps the generated references correctly grouped;
and
images.lua translates file paths which make sense beside an Org
document into paths which make sense on the published website.
The converter is a normal Gleam program: it creates output directories,\nskips files which are already up to date, invokes Pandoc and reports\nfailures as Result values. Once conversion finishes, Blogatto reads\nthe generated posts, builds their pages and RSS feed, and copies static\nassets into dist/. Lustre supplies the HTML elements used by the site\nlayout.
There is deliberately not much more to say. I could be using\nOrg-Publish to automate\nmost of this, but there are some quality of life features that I\nalways find it hard to make them work when generating html with it\n(syntax highlighting is just one of them).
\nNothing really changed here, Nix is still the ducktape that makes\neverything work. Entering nix develop provides gleam, pandoc,\nmake and the other build-time dependencies.\nDevenv makes that shell pleasant to use\ninteractively, while the same flake reproduces the build environment\nwithout relying on whatever happens to be installed globally.
# ...\npackages = {\n default = inputs'.nix-gleam.packages.buildGleamApplication {\n src = ./.;\n # `fs` (transitive dependency from blogatto -> filespy) builds a\n # NIF using the `pc` rebar3 plugin, bundle it so pure builds don't\n # hit hexpm.\n rebar3Package = pkgs.rebar3WithPlugins {\n plugins = with pkgs.beamPackages; [ pc ];\n };\n };\n};\n# nix fmt + nix flake check (auto-wired by flakeModule)\ntreefmt = {\n projectRootFile = "flake.nix";\n programs.gleam.enable = true;\n programs.nixfmt.enable = true;\n};\ndevenv.shells.default = {\n # ...\n packages =\n with pkgs;\n [\n gnumake\n pandoc\n ]\n ++ lib.optionals stdenv.isLinux [ inotify-tools ]\n ++ [ config.packages.default ];\n languages.gleam = {\n enable = true;\n };\n languages.lua = {\n enable = true;\n lsp.enable = true;\n };\n enterShell = ''\n echo "Starting Development Environment..."\n '';\n};\n# ...From inside the development environment the complete build is intentionally mundane:
\nmake run\n# or\nmake devThis website has a (somewhat absurd) number of tools for a simple static page. Each one of these tools, however, has a narrow job. Org-mode holds the rich source document. Pandoc reduces it to a portable interchange format. Blogatto turns that format into a site. Gleam + Lustre give me a type-checked project that generates all the static html. Nix gives me a reproducible development environment.
\nThe centre of the system is still Emacs, it's my (stubborn) decision to keep the act of writing, the structure of the document and the computations which support it all in one place. Org-mode is superior to Markdown for that job because it is a document model I can interact with while thinking.
\nUNIX-Hater Handbook. IDG Books Worldwide, Inc.
\nThe Computer Journal27 (2): 97–111.
\nJournal of Statistical Software46: 1–24.
","headings":[{"level":2,"text":"Blogging with Gleam, Org-mode and Pandoc","id":"blogging-with-gleam-org-mode-and-pandoc"},{"level":1,"text":"Why keep everything inside Emacs?","id":"why-keep-everything-inside-emacs"},{"level":1,"text":"Why Org-mode instead of Markdown?","id":"why-org-mode-instead-of-markdown"},{"level":1,"text":"Pandoc as a boundary","id":"pandoc-as-a-boundary"},{"level":1,"text":"Gleam, Blogatto and Lustre","id":"gleam-blogatto-and-lustre"},{"level":1,"text":"Reproducibility with Nix","id":"reproducibility-with-nix"},{"level":1,"text":"Conclusion","id":"conclusion"},{"level":1,"text":"Bibliography","id":"bibliography"}]}}