The Mark issue generator
Two half-finished newsletter builders, what is broken in them today, and the Markdown-driven flow they were meant to become
Two issues of The Mark live under content/portfolio/the-mark/, each with its own generator. The idea was a repeatable flow: keep the design in a template, keep the writing in a data file, and run a script to produce the finished issue. The design half works. The writing half never got where it was going.
How it works today
Each issue folder holds four things: a build.js, a template.html full of {{placeholder}} tokens, a JSON file with the issue's content, and the generated index.html. The script reads the template, builds HTML strings from the JSON, swaps every placeholder, and writes the finished page. There is also a -BLANK.json in each folder: an empty scaffold to copy when starting a new issue.
What is broken
Both generators read a file called newsletter-data.json, and neither folder contains one. The 2017 data lives in 2017-newsletter-data.json and the 2021 data in 2021-01.json. Running either script today throws ENOENT before it does anything. Whoever renamed the data files did not update the two readFileSync calls.
That is a one-line fix in each script, but it is worth doing as part of the redesign below rather than on its own, because the input format is going to change anyway.
Where it should go
Writing an issue currently means editing JSON by hand. That is a poor writing surface: prose has to be escaped, every paragraph carries HTML tags inside a string, and a stray comma breaks the build with an error that says nothing about which section it came from. The intent was always to write in Markdown and let the script deal with the structure.
The shape to aim for:
- One Markdown file per issue, with a small front-matter block for the fields that are genuinely data — title, date, the index figures, the description and keywords.
- Body sections written as ordinary Markdown, with headings marking the section boundaries so the script can derive the nav from them instead of being handed a separate
navarray that has to be kept in sync by hand. - One generator shared by every issue, rather than a copy per folder that drifts. The two current scripts are already ninety per cent identical; the differences are the 2021 callout image and a hardcoded paragraph of stimulus-bill copy sitting inside
build.jswhere content does not belong. - Output still a plain committed
index.html, matching how the sitemap and knowledge base already work here.
Notes for when we pick this up
The build inputs are listed in .assetsignore, so the scripts, templates and JSON are not served — only the finished issues are. Keep that true of whatever replaces them.
Both CV pages link 2017-11/2017-index.html as a portfolio sample, so that file's URL should survive any reorganisation. The 2021 issue has no inbound link yet.