kmalloc.org/build.py
squid 7bc7b8789f feat: add an RSS 2.0 feed for the news
- build /news/feed.xml and /it/news/feed.xml with the latest 20 posts, full text and absolute links
- add the feed autodiscovery link to every page and a visible link on the news pages
- document the feed in the README
2026-11-12 18:41:38 +01:00

340 lines
14 KiB
Python

#!/usr/bin/env python3
"""Build the kmalloc.org static site (plain HTML, no JavaScript, standard library only).
Usage: build.py [output-dir] (default: preview)
Layout:
templates/ page chrome: base.html, header.html, footer.html, ...
static/style.css the one stylesheet, inlined into every page
content/site.toml values shared by every page (contact, bitcoin address, manifesto version)
content/<lang>/lang.toml the chrome strings of one language
content/<lang>/*.html pages: front matter, then an HTML fragment
content/<lang>/news/*.md news posts: YYYY-MM-DD-slug.md, front matter, then Markdown
A page starts with a front matter block:
---
id: people pairs the page with its translation
path: /people.html where it is published
nav: people menu entry highlighted on this page
title: ...
description: ...
---
Placeholders {{name}} are replaced with values from site.toml, lang.toml and the page itself.
An unknown placeholder stops the build."""
import html, os, re, shutil, sys, tomllib
from email.utils import format_datetime
from datetime import datetime, timezone
from xml.sax.saxutils import escape as xml_escape
HERE = os.path.dirname(os.path.abspath(__file__))
OUT = os.path.abspath(sys.argv[1] if len(sys.argv) > 1 else os.path.join(HERE, "preview"))
LANGS = ("en", "it")
NAV = ("home", "manifesto", "people", "services", "news")
NEWS_ON_HOME = 3
NEWS_IN_FEED = 20
POST_NAME = re.compile(r"^(\d{4}-\d{2}-\d{2})-([a-z0-9]+(?:-[a-z0-9]+)*)$")
# Files copied as they are: published name -> source.
ASSETS = {
"favicon.svg": "logo/svg/favicon-auto.svg",
"favicon-auto.svg": "logo/svg/favicon-auto.svg",
"logo-auto.svg": "logo/svg/logo-auto.svg",
"favicon.ico": "logo/web/favicon.ico",
"apple-touch-icon.png": "logo/web/apple-touch-icon.png",
"fonts/terminess.woff2": "fonts/terminess.woff2",
"badges/w3c-html5.png": "badges/w3c-html5.png",
"badges/w3c-css.png": "badges/w3c-css.png",
}
def fail(msg):
raise SystemExit(f"build.py: {msg}")
def read(*parts):
with open(os.path.join(HERE, *parts), encoding="utf-8") as f:
return f.read()
def write(rel, text):
path = os.path.join(OUT, rel)
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w", encoding="utf-8") as f:
f.write(text)
def toml(*parts):
with open(os.path.join(HERE, *parts), "rb") as f:
return tomllib.load(f)
def parse(text, name):
"""Split 'front matter, then body' into (dict, body)."""
m = re.match(r"---\n(.*?)\n---\n(.*)\Z", text, re.S)
if not m:
fail(f"{name}: missing front matter")
meta = {}
for line in m.group(1).splitlines():
key, sep, value = line.partition(": ")
if not sep:
fail(f"{name}: bad front matter line {line!r}")
meta[key.strip()] = value.strip()
return meta, m.group(2)
def render(text, ctx, name):
def sub(m):
if m.group(1) not in ctx:
fail(f"{name}: unknown placeholder {{{{{m.group(1)}}}}}")
return ctx[m.group(1)]
return re.sub(r"\{\{(\w+)\}\}", sub, text)
# ---------------------------------------------------------------- Markdown
def no_em_dash(md):
"""The manifesto sources use em dashes; the site does not: headings 'NN — Title' become 'NN. Title',
'Word — Title' becomes 'Word: Title', attribution lines lose the dash, parenthetical dashes become commas."""
md = re.sub(r"^(#+ )(\d\d) — ", r"\1\2. ", md, flags=re.M)
md = re.sub(r"^(#+ [^\d\n][^—\n]*?) — ", r"\1: ", md, flags=re.M)
md = re.sub(r"^> — ", "> ", md, flags=re.M)
for a, b in ((" — where technically feasible — ", ", where technically feasible, "),
(" — dove tecnicamente possibile — ", ", dove tecnicamente possibile, "),
(" — and continues", ", and continues"),
(" — e continua", ", e continua")):
md = md.replace(a, b)
md = md.replace("kmalloc.org — ", "kmalloc.org: ")
assert "—" not in md, [l for l in md.splitlines() if "—" in l]
return md
def inline(s):
s = html.escape(s, quote=False)
s = re.sub(r"`([^`]+)`", r"<code>\1</code>", s)
s = re.sub(r"\[([^\]]+)\]\(([^)\s]+)\)", r'<a href="\2">\1</a>', s)
s = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", s)
s = re.sub(r"(?<!\*)\*(?!\s)(.+?)(?<!\s)\*(?!\*)", r"<em>\1</em>", s)
return s
def slug(heading):
m = re.match(r"(\d\d)\b", heading)
if m:
return m.group(1)
h = heading.lower()
if h.startswith(("preamble", "preambolo")):
return "preamble"
if h.startswith(("our commitments", "i nostri impegni")):
return "commitments"
if h.startswith(("epilogue", "epilogo")):
return "epilogue"
return re.sub(r"[^a-z0-9]+", "-", h).strip("-")
def md_to_html(md):
"""Headings (##), paragraphs, quotes, bullet lists and inline markup. Returns (title, toc, html)."""
out, toc = [], []
para, quote, items = [], [], []
def flush():
nonlocal para, quote, items
if para:
out.append("<p>\n" + "\n".join(para) + "\n</p>\n")
para = []
if quote:
out.append("<blockquote>\n<p>\n" + "\n".join(quote) + "\n</p>\n</blockquote>\n")
quote = []
if items:
out.append("<ul>\n" + "\n".join(f"<li>{i}</li>" for i in items) + "\n</ul>\n")
items = []
title = ""
for raw in md.splitlines():
line = raw.rstrip("\n")
br = line.endswith(" ")
s = line.strip()
if not s:
flush()
continue
if s.startswith("# "):
flush()
title = s[2:]
continue
if s.startswith("## "):
flush()
h = s[3:]
sl = slug(h)
toc.append((sl, h))
out.append(f'<h2 id="{sl}">{inline(h)}</h2>\n')
continue
if s.startswith("> "):
if para or items:
flush()
quote.append(inline(s[2:]) + ("<br>" if br else ""))
continue
if s.startswith("- "):
if para or quote:
flush()
items.append(inline(s[2:]))
continue
if quote or items:
flush()
para.append(inline(s))
flush()
return title, toc, "".join(out)
# ---------------------------------------------------------------- site model
def load_pages(lang):
"""Pages of one language: static pages from content/<lang>/*.html and posts from content/<lang>/news/*.md."""
pages = []
folder = os.path.join(HERE, "content", lang)
for fn in sorted(os.listdir(folder)):
if fn.endswith(".html"):
meta, body = parse(read("content", lang, fn), f"content/{lang}/{fn}")
for key in ("id", "path", "nav", "title", "description"):
if key not in meta:
fail(f"content/{lang}/{fn}: front matter lacks '{key}'")
if meta["nav"] not in NAV:
fail(f"content/{lang}/{fn}: unknown nav '{meta['nav']}'")
pages.append(dict(meta, lang=lang, kind="page", body=body, src=f"content/{lang}/{fn}"))
news_dir = os.path.join(folder, "news")
if os.path.isdir(news_dir):
prefix = "" if lang == "en" else "/it"
for fn in sorted(os.listdir(news_dir)):
if not fn.endswith(".md"):
continue
m = POST_NAME.match(fn[:-3])
if not m:
fail(f"content/{lang}/news/{fn}: name must be YYYY-MM-DD-slug.md")
src = f"content/{lang}/news/{fn}"
meta, body = parse(read("content", lang, "news", fn), src)
if "title" not in meta:
fail(f"{src}: front matter lacks 'title'")
if "—" in body or "—" in meta["title"]:
fail(f"{src}: no em dashes, please")
pages.append(dict(meta, lang=lang, kind="post", id="news/" + fn[:-3], date=m.group(1), nav="news",
path=f"{prefix}/news/{m.group(2)}.html", body=body, src=src,
description=meta.get("summary", meta["title"])))
return pages
def rss(lang, st, site, lang_pages):
"""RSS 2.0 feed of the news of one language: the latest posts, full text, absolute links."""
base = site["base_url"]
posts = sorted((p for p in lang_pages if p["kind"] == "post"), key=lambda p: p["date"], reverse=True)[:NEWS_IN_FEED]
def stamp(d):
return format_datetime(datetime.strptime(d, "%Y-%m-%d").replace(tzinfo=timezone.utc))
items = []
for p in posts:
text = md_to_html(p["body"])[2].replace('href="/', f'href="{base}/')
items.append(f"""<item>
<title>{xml_escape(p["title"])}</title>
<link>{base}{p["path"]}</link>
<guid isPermaLink="true">{base}{p["path"]}</guid>
<pubDate>{stamp(p["date"])}</pubDate>
<description>{xml_escape(text)}</description>
</item>
""")
built = f"<lastBuildDate>{stamp(posts[0]['date'])}</lastBuildDate>\n" if posts else ""
url = f"{base}{st['url_news']}"
return f"""<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
<channel>
<title>kmalloc.org: {xml_escape(st["nav_news"])}</title>
<link>{url}</link>
<description>{xml_escape(st["news_p"])}</description>
<language>{lang}</language>
{built}<atom:link href="{url}feed.xml" rel="self" type="application/rss+xml"/>
{"".join(items)}</channel>
</rss>
"""
def build():
css = read("static", "style.css").strip("\n")
tpl = {n[:-5]: read("templates", n) for n in os.listdir(os.path.join(HERE, "templates")) if n.endswith(".html")}
site = toml("content", "site.toml")
site["contact_shown"] = site["contact"].replace("@", " (at) ") # no mailto link, against address harvesters
strings = {lang: toml("content", lang, "lang.toml") for lang in LANGS}
pages = {lang: load_pages(lang) for lang in LANGS}
by_id = {(p["id"], p["lang"]): p for lang in LANGS for p in pages[lang]}
# Manifesto: the user's own Markdown files, rendered once per language.
manifesto = {}
for lang in LANGS:
title, toc, body = md_to_html(no_em_dash(read(f"MANIFESTO.{lang}.md")))
manifesto[lang] = dict(
manifesto_title=html.escape(title),
manifesto_toc="\n".join(f'<li><a href="#{sl}">{inline(h)}</a></li>' for sl, h in toc),
manifesto_body=body)
def news_lists(lang):
posts = sorted((p for p in pages[lang] if p["kind"] == "post"), key=lambda p: p["date"], reverse=True)
def li(p):
line = f'<li><time datetime="{p["date"]}">{p["date"]}</time> <a href="{p["path"]}">{html.escape(p["title"], quote=False)}</a>'
if p.get("summary"):
line += ": " + html.escape(p["summary"], quote=False)
return line + "</li>"
items = "\n".join(li(p) for p in posts)
full = f"<ul>\n{items}\n</ul>" if posts else f"<p>\n{strings[lang]['news_empty']}\n</p>"
return full, items, posts[:NEWS_ON_HOME]
news = {lang: news_lists(lang) for lang in LANGS}
for lang in LANGS:
other = "it" if lang == "en" else "en"
st = strings[lang]
for p in pages[lang]:
name = p["src"]
alt = by_id.get((p["id"], other))
ctx = dict(site, **st, **manifesto[lang])
page_title = p["title"] if p["kind"] == "page" else "kmalloc.org: " + p["title"]
ctx.update(css=css, title=p["title"], description=p["description"], path=p["path"],
title_html=html.escape(page_title), post_title=html.escape(p["title"]), description_attr=html.escape(p["description"], quote=True),
doc_url=site["base_url"] + p["path"], date=p.get("date", ""))
for k in NAV:
ctx["cur_" + k] = ' aria-current="page"' if p["nav"] == k else ""
ctx["alt_url"] = alt["path"] if alt else ""
ctx["alt_switch"] = p.get("switch") or (alt["path"] if alt else strings[other]["url_news"])
ctx["alt_links"] = (f'<link rel="alternate" hreflang="{other}" href="{alt["path"]}">\n'
f'<link rel="alternate" hreflang="{lang}" href="{p["path"]}">') if alt else ""
full, items, latest = news[lang]
ctx["news_list"] = full
ctx["latest_news"] = render(tpl["latest-news"], dict(ctx, news_items="\n".join(
f'<li><time datetime="{x["date"]}">{x["date"]}</time> <a href="{x["path"]}">{html.escape(x["title"], quote=False)}</a></li>'
for x in latest)), "templates/latest-news.html") if latest else ""
if p["kind"] == "post":
_, _, post_html = md_to_html(p["body"])
ctx["post_body"] = post_html
ctx["content"] = render(tpl["news-post"], ctx, "templates/news-post.html")
lead = "news"
else:
ctx["content"] = render(p["body"].strip("\n") + "\n", ctx, name)
lead = p.get("lead", "back")
ctx["lead"] = render(tpl["lead-" + lead], ctx, f"templates/lead-{lead}.html")
ctx["badges"] = render(tpl["badges"], dict(ctx, doc_q=ctx["doc_url"].replace(":", "%3A").replace("/", "%2F")),
"templates/badges.html")
ctx["header"] = render(tpl["header"], ctx, "templates/header.html")
ctx["footer"] = render(tpl["footer"], ctx, "templates/footer.html")
rel = p["path"].lstrip("/")
write(rel + "index.html" if rel == "" or rel.endswith("/") else rel, render(tpl["base"], ctx, "templates/base.html"))
for lang in LANGS:
write(strings[lang]["url_news"].lstrip("/") + "feed.xml", rss(lang, strings[lang], site, pages[lang]))
for dest, src in ASSETS.items():
target = os.path.join(OUT, dest)
os.makedirs(os.path.dirname(target), exist_ok=True)
shutil.copy(os.path.join(HERE, src), target)
write("robots.txt", "User-agent: *\nDisallow: /\n")
count = sum(len(v) for v in pages.values())
print(f"built {count} pages into {OUT}")
build()