Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
#!/usr/bin/env python3
# SculptForge - open source digital sculpting
# SPDX-License-Identifier: GPL-3.0-or-later
"""Builds the website's user guide (website/guide/*.html) from docs/guide/*.md.
python3 tools/guide/build_site.py # write website/guide
python3 tools/guide/build_site.py --check # also fail on broken links, images or characters
python3 tools/guide/build_site.py --out DIR # write somewhere else (tests)
Standard library only. It understands the same Markdown subset as the in-app reader (src/core/Guide.cpp):
one "# Title", "##"/"###" headings, paragraphs with **bold**, *italic*, `code`, <kbd>keys</kbd> and links,
"- "/"1. " lists with one nesting level, pipe tables, ``` code blocks, "> **Label:** ..." callouts, images on
their own line and "---" rules. The pages use website/style.css and website/motion.js.
"""
import argparse
import html
import json
import pathlib
import re
import shutil
import struct
import sys
ROOT = pathlib.Path(__file__).resolve().parents[2]
SRC = ROOT / "docs" / "guide"
SITE = "https://sculptforge.app/"
# Chapters that were renamed: the old page stays as a small redirect so links from elsewhere keep working.
REDIRECTS: dict[str, str] = {}
CALLOUTS = {"tip": "Tip", "note": "Note", "experienced": "Experienced sculptor?", "not-yet": "Not yet", "warning": "Warning",
"important": "Important"}
# ---------------------------------------------------------------------------
# Markdown subset -> HTML
# ---------------------------------------------------------------------------
def slugify(text: str) -> str:
"""GitHub-style anchors, the same rule as guide::slugify."""
out = []
for ch in text:
if ch.isascii() and ch.isalnum():
out.append(ch.lower())
elif ch == " ":
out.append("-")
elif ch in "-_" or ord(ch) >= 0x80:
out.append(ch)
return "".join(out)
def md_link(target: str) -> str:
"""docs/guide links (x.md#y) become site links (x.html#y)."""
if re.match(r"^(https?:|mailto:)", target):
return target
path, _, anchor = target.partition("#")
if path.endswith(".md"):
path = path[:-3] + ".html"
return path + ("#" + anchor if anchor else "")
ENTITIES = {"&": "&", "<": "<", ">": ">", """: '"', " ": " "}
def inline(text: str, links: list) -> str:
"""Inline formatting to HTML. Appends every link target to LINKS (for --check)."""
out = []
i = 0
bold = italic = False
n = len(text)
while i < n:
c = text[i]
if c == "\\" and i + 1 < n and not text[i + 1].isalnum() and not text[i + 1].isspace():
out.append(html.escape(text[i + 1]))
i += 2
continue
if c == "`":
close = text.find("`", i + 1)
if close != -1:
out.append("<code>" + html.escape(text[i + 1:close]) + "</code>")
i = close + 1
continue
if text.startswith("<kbd>", i):
close = text.find("</kbd>", i + 5)
if close != -1:
out.append("<kbd>" + html.escape(text[i + 5:close]) + "</kbd>")
i = close + 6
continue
if c == "<" and (text.startswith("http://", i + 1) or text.startswith("https://", i + 1)):
close = text.find(">", i + 1)
if close != -1:
url = text[i + 1:close]
links.append(url)
out.append(f'<a href="{html.escape(url)}">{html.escape(url)}</a>')
i = close + 1
continue
if c == "&":
for name, value in ENTITIES.items():
if text.startswith(name, i):
out.append(html.escape(value))
i += len(name)
break
else:
out.append("&")
i += 1
continue
if text.startswith("**", i):
out.append("</strong>" if bold else "<strong>")
bold = not bold
i += 2
continue
if c == "*":
can_open = not italic and i + 1 < n and not text[i + 1].isspace() and text.find("*", i + 1) != -1
can_close = italic and i > 0 and not text[i - 1].isspace()
if can_open or can_close:
out.append("</em>" if italic else "<em>")
italic = not italic
i += 1
continue
if c == "[":
depth = 0
close = -1
k = i
while k < n:
if text[k] == "`":
e = text.find("`", k + 1)
if e == -1:
break
k = e + 1
continue
if text[k] == "[":
depth += 1
elif text[k] == "]":
depth -= 1
if depth == 0:
close = k
break
k += 1
if close != -1 and close + 1 < n and text[close + 1] == "(":
end = text.find(")", close + 2)
if end != -1:
target = text[close + 2:end].strip()
links.append(target)
label = inline(text[i + 1:close], [])
ext = ' rel="noopener"' if target.startswith("http") else ""
out.append(f'<a href="{html.escape(md_link(target))}"{ext}>{label}</a>')
i = end + 1
continue
out.append(html.escape(c))
i += 1
if italic:
out.append("</em>")
if bold:
out.append("</strong>")
return "".join(out)
def table_cells(line: str) -> list:
line = line.strip()
if line.startswith("|"):
line = line[1:]
if line.endswith("|") and not line.endswith("\\|"):
line = line[:-1]
cells, start, in_code, k = [], 0, False, 0
while k <= len(line):
if k < len(line) and not in_code and line.startswith("<kbd>", k):
close = line.find("</kbd>", k)
if close != -1:
k = close + 6
continue
if k < len(line) and line[k] == "`":
in_code = not in_code
if k == len(line) or (line[k] == "|" and not in_code and (k == 0 or line[k - 1] != "\\")):
cells.append(line[start:k].strip())
start = k + 1
k += 1
return cells
def is_separator(line: str) -> bool:
cells = table_cells(line)
return bool(cells) and all(c and set(c) <= set("-: ") for c in cells)
class Page:
def __init__(self, name: str, text: str, used=None, shift: int = 0):
self.name = name # "masking.md"
self.used = set() if used is None else used # heading anchors taken (shared by What's New's parts)
self.shift = shift # added to heading levels (What's New's folded versions: ### becomes h4)
self.title = ""
self.headings = [] # (level, text, anchor)
self.links = []
self.images = []
self.chars = text
self.text_blocks = [] # (anchor, heading, plain text) for the search index
self.body = self.render(text)
def render(self, md: str) -> str:
lines = md.split("\n")
out = []
used = self.used
para = []
list_stack = [] # open list tags, by nesting level
item_open = [False, False]
section = ("", "")
search_text = []
def plain(s):
return re.sub(r"<[^>]+>", "", html.unescape(s))
def flush_para():
if para:
text = " ".join(para)
rendered = inline(text, self.links)
out.append(f"<p>{rendered}</p>")
search_text.append(plain(rendered))
para.clear()
def close_lists(level=0):
while len(list_stack) > level:
lvl = len(list_stack) - 1
if item_open[lvl]:
out.append("</li>")
item_open[lvl] = False
out.append(f"</{list_stack.pop()}>")
def end_section():
if search_text:
self.text_blocks.append((section[0], section[1], " ".join(search_text)))
search_text.clear()
i = 0
pending_item = None # [level, tag, text] being collected (wrapped list items)
def flush_item():
nonlocal pending_item
if pending_item:
lvl, tag, text = pending_item
rendered = inline(text, self.links)
out.append(rendered)
search_text.append(plain(rendered))
pending_item = None
while i < len(lines):
raw = lines[i]
t = raw.strip()
if not t:
flush_para()
flush_item()
close_lists()
i += 1
continue
if t.startswith("<!--"):
flush_para(); flush_item(); close_lists()
while i < len(lines) and "-->" not in lines[i]:
i += 1
i += 1
continue
if t.startswith("```"):
flush_para(); flush_item(); close_lists()
lang = t[3:].strip()
indent = len(raw) - len(raw.lstrip(" "))
code = []
i += 1
while i < len(lines) and not lines[i].strip().startswith("```"):
line = lines[i]
drop = min(indent, len(line) - len(line.lstrip(" ")))
code.append(line[drop:])
i += 1
i += 1
cls = f' class="language-{html.escape(lang)}"' if lang else ""
out.append(f'<div class="code-block"><pre class="code"><code{cls}>{html.escape(chr(10).join(code))}'
f'</code></pre><button class="copy" type="button" aria-label="Copy">Copy</button></div>')
search_text.append(" ".join(code))
continue
m = re.match(r"^(#{1,6}) (.*)$", t)
if m:
flush_para(); flush_item(); close_lists()
level = min(len(m.group(1)), 3)
if level > 1:
level = min(level + self.shift, 4)
rendered = inline(m.group(2).strip(), self.links)
text = plain(rendered)
anchor = slugify(text)
base, k = anchor, 1
while anchor in used:
anchor = f"{base}-{k}"
k += 1
used.add(anchor)
if level == 1 and not self.title:
self.title = text
out.append(f'<h1 id="{anchor}">{rendered}</h1>')
section = ("", text)
else:
end_section()
section = (anchor, text)
self.headings.append((level, text, anchor))
out.append(f'<h{level} id="{anchor}">{rendered}'
f'<a class="anchor" href="#{anchor}" aria-label="Link to this section">#</a></h{level}>')
i += 1
continue
if t.startswith("|") and i + 1 < len(lines) and is_separator(lines[i + 1]):
flush_para(); flush_item(); close_lists()
rows = [table_cells(t)]
i += 2
while i < len(lines) and lines[i].strip().startswith("|"):
rows.append(table_cells(lines[i]))
i += 1
cols = len(rows[0])
head = "".join(f"<th>{inline(c, self.links)}</th>" for c in rows[0])
body = "".join("<tr>" + "".join(f"<td>{inline(c, self.links)}</td>" for c in (r + [""] * cols)[:cols])
+ "</tr>" for r in rows[1:])
out.append(f'<div class="table-wrap"><table><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table></div>')
search_text.append(" ".join(plain(inline(c, [])) for r in rows for c in r))
continue
if t.startswith(">"):
flush_para(); flush_item(); close_lists()
parts = []
while i < len(lines) and lines[i].strip().startswith(">"):
parts.append(lines[i].strip()[1:].strip())
i += 1
text = " ".join(parts)
kind = "note"
m2 = re.match(r"^\*\*([^*]+?):?\*\*", text)
if m2:
label = m2.group(1).rstrip(":").strip()
for key, name in CALLOUTS.items():
if label.lower() == name.lower():
kind = key
rendered = inline(text, self.links)
out.append(f'<aside class="callout callout-{kind}"><p>{rendered}</p></aside>')
search_text.append(plain(rendered))
continue
m = re.match(r"^!\[(.*)\]\((.*)\)$", t)
if m:
flush_para(); flush_item(); close_lists()
alt, src = m.group(1), m.group(2).strip()
self.images.append(src)
size = image_size(SRC / src)
dims = f' width="{size[0]}" height="{size[1]}"' if size else ""
out.append(f'<figure class="shot"><a href="{html.escape(src)}" class="zoom"><img src="{html.escape(src)}" '
f'alt="{html.escape(alt)}"{dims} loading="lazy" decoding="async"></a>'
f'<figcaption>{inline(alt, [])}</figcaption></figure>')
search_text.append(alt)
i += 1
continue
if re.match(r"^-{3,}$", t.replace(" ", "")) and not para:
flush_item(); close_lists()
out.append("<hr>")
i += 1
continue
mb = re.match(r"^[-*+] (.*)$", t)
mn = re.match(r"^(\d{1,4})[.)] (.*)$", t)
if mb or mn:
flush_para(); flush_item()
indent = len(raw) - len(raw.lstrip(" "))
level = 1 if indent >= 2 else 0
tag = "ul" if mb else "ol"
if len(list_stack) > level + 1 or (len(list_stack) == level + 1 and list_stack[level] != tag):
close_lists(level)
if len(list_stack) == level + 1:
if item_open[level]:
out.append("</li>")
elif len(list_stack) < level + 1:
while len(list_stack) < level + 1:
start = ""
if tag == "ol" and mn and mn.group(1) != "1":
start = f' start="{mn.group(1)}"'
out.append(f"<{tag}{start}>")
list_stack.append(tag)
item_open[len(list_stack) - 1] = False
out.append("<li>")
item_open[level] = True
pending_item = [level, tag, (mb or mn).group(mb and 1 or 2)]
i += 1
continue
if pending_item:
pending_item[2] += " " + t
i += 1
continue
para.append(t)
i += 1
flush_para()
flush_item()
close_lists()
end_section()
return "\n".join(out)
def image_size(path: pathlib.Path):
"""(width, height) of a JPEG or PNG, or None."""
try:
data = path.read_bytes()
except OSError:
return None
if data[:8] == b"\x89PNG\r\n\x1a\n":
return struct.unpack(">II", data[16:24])
if data[:2] == b"\xff\xd8":
i = 2
while i + 9 < len(data):
if data[i] != 0xFF:
i += 1
continue
marker = data[i + 1]
if marker in (0xC0, 0xC1, 0xC2):
h, w = struct.unpack(">HH", data[i + 5:i + 9])
return w, h
seg = struct.unpack(">H", data[i + 2:i + 4])[0]
i += 2 + seg
return None
# ---------------------------------------------------------------------------
# What's New (whats-new.md): the data in each version's ```features block, the newest versions in full and the older
# ones folded into groups. Mirrors src/core/WhatsNew.cpp, which the app uses for the same chapter and its pop-up.
# ---------------------------------------------------------------------------
WHATS_NEW = "whats-new.md"
WN_DETAILED, WN_SERIES_GROUPS, WN_MAX_HIGHLIGHTS = 3, 2, 6
WN_KEYS = {"date", "tagline", "highlight", "title", "line", "image", "action", "link", "clip", "frames"}
def version_parts(v: str) -> list:
return [int(x) if x.isdigit() else 0 for x in v.split(".")]
def compare_versions(a: str, b: str) -> int:
x, y = version_parts(a), version_parts(b)
n = max(len(x), len(y))
x, y = x + [0] * (n - len(x)), y + [0] * (n - len(y))
return (x > y) - (x < y)
def series(v: str) -> str:
p = version_parts(v) + [0, 0]
return f"{p[0]}.{p[1]}"
def project_version() -> str:
m = re.search(r"project\(SculptForge VERSION (\S+)", (ROOT / "CMakeLists.txt").read_text(encoding="utf-8"))
return m.group(1) if m else ""
def project_prerelease() -> str:
"""CMakeLists.txt's SCULPTFORGE_PRERELEASE ("beta.1" while a beta of the project version is out, else "")."""
m = re.search(r'^set\(SCULPTFORGE_PRERELEASE "([^"]*)"\)', (ROOT / "CMakeLists.txt").read_text(encoding="utf-8"), re.M)
return m.group(1) if m else ""
def parse_features(text: str) -> dict:
"""The features block: date, tagline, highlights, then cards (each starts with title:). Raises ValueError."""
v = {"date": "", "tagline": "", "highlights": [], "cards": []}
for k, raw in enumerate(text.split("\n"), 1):
line = raw.strip()
if not line or line.startswith("#"):
continue
key, sep, value = line.partition(":")
key, value = key.strip(), value.strip()
if not sep or key not in WN_KEYS:
raise ValueError(f"line {k}: " + (f"unknown key '{key}'" if sep else "expected 'key: value'"))
if key == "title":
v["cards"].append({"title": value, "line": "", "image": "", "action": "", "link": "", "clip": "", "frames": ""})
elif key in ("line", "image", "action", "link", "clip", "frames"):
if not v["cards"]:
raise ValueError(f"line {k}: '{key}' before the card's 'title'")
if key == "frames" and not re.fullmatch(r"\S+ \d{1,2}x\d{1,2} \d{1,2}", value):
raise ValueError(f"line {k}: frames wants 'path COLSxROWS FPS'")
v["cards"][-1][key] = value
elif key == "highlight":
v["highlights"].append(value)
else:
v[key] = value
for c in v["cards"]:
if not (c["title"] and c["line"] and c["action"]):
raise ValueError(f"card '{c['title']}' needs a title, a line and an action")
return v
def split_highlight(h: str):
title, sep, rest = h.partition(": ")
return (title.strip(), rest.strip()) if sep else ("", h)
def build_whats_new(md: str, current: str):
"""(intro markdown, versions, groups, problems). Versions newer than CURRENT are left out; each version has
version, anchor, date, tagline, highlights, cards and body (its markdown without the heading and the block)."""
lines = md.split("\n")
starts = [i for i, l in enumerate(lines) if re.match(r"^## Version \S+$", l.strip())]
intro = "\n".join(lines[:starts[0]] if starts else lines)
versions, problems = [], []
for n, s in enumerate(starts):
end = starts[n + 1] if n + 1 < len(starts) else len(lines)
name = lines[s].strip()[len("## Version "):]
body = lines[s + 1:end]
data = {"date": "", "tagline": "", "highlights": [], "cards": []}
k = 0
while k < len(body) and not body[k].strip():
k += 1
if k < len(body) and body[k].strip() == "```features":
e = k + 1
while e < len(body) and body[e].strip() != "```":
e += 1
try:
data = parse_features("\n".join(body[k + 1:e]))
except ValueError as err:
problems.append(f"{WHATS_NEW}: Version {name}: {err}")
body = body[:k] + body[e + 1:]
if current and compare_versions(name, current) > 0:
continue # not released yet
versions.append(dict(data, version=name, anchor=slugify("Version " + name), body="\n".join(body)))
detailed = min(WN_DETAILED, len(versions))
groups, seen = [], []
for i in range(detailed, len(versions)):
s = series(versions[i]["version"])
if s not in seen:
seen.append(s)
slot = min(seen.index(s), WN_SERIES_GROUPS)
while len(groups) <= slot:
groups.append({"versions": []})
groups[slot]["versions"].append(i)
for g, group in enumerate(groups):
newest, oldest = versions[group["versions"][0]], versions[group["versions"][-1]]
if len(group["versions"]) == 1:
label = newest["version"]
elif g == WN_SERIES_GROUPS:
label = series(newest["version"]) + " and earlier"
elif any(series(versions[i]["version"]) == series(newest["version"]) for i in range(detailed)):
label = f"{oldest['version']} to {newest['version']}"
else:
label = series(newest["version"]) + ".x"
order = sorted(group["versions"], key=lambda i: -len(versions[i]["highlights"])) # stable: newest first on ties
picked, rnd = [], 0
while len(picked) < WN_MAX_HIGHLIGHTS:
any_left = False
for i in order:
hs = versions[i]["highlights"]
if rnd < len(hs):
any_left = True
if len(picked) < WN_MAX_HIGHLIGHTS:
picked.append((i, hs[rnd]))
if not any_left:
break
rnd += 1
picked.sort(key=lambda p: p[0])
group.update(label=label, anchor="versions-" + slugify(label), highlights=[h for _, h in picked])
group["summary"] = ", ".join(t for t, _ in map(split_highlight, group["highlights"]) if t)
return intro, versions, groups, problems
def card_link(card: dict) -> str:
"""Where a card's button goes on the website: its link, else its guide: action; "" for app-only actions."""
target = card.get("link") or (card["action"][len("guide:"):] if card["action"].startswith("guide:") else "")
return md_link(target) if target else ""
class WhatsNewPage(Page):
"""whats-new.md: version bands with their feature cards and "All changes", then the folded groups."""
def __init__(self, name: str, text: str):
intro, self.versions, self.groups, self.problems = build_whats_new(text, project_version())
self.detailed = min(WN_DETAILED, len(self.versions))
# The plain chapter (released versions, no data blocks): headings, links, search and the checks.
plain = intro + "\n" + "\n".join(f"## Version {v['version']}\n{v['body']}" for v in self.versions)
super().__init__(name, plain)
self.chars = text
# Every card picture, also those of a version not released yet (it ships with the next one).
# Clips too: the video the website plays, and the frame sheet the app plays (shipped with the guide).
self.images += [src for src in re.findall(r"^image:\s*(\S+)\s*$", text, re.M) if src not in self.images]
self.images += [src for src in re.findall(r"^(?:clip|frames):\s*(\S+)", text, re.M) if src not in self.images]
for v in self.versions:
for c in v["cards"]:
if c.get("link"):
self.links.append(c["link"])
elif c["action"].startswith("guide:"):
self.links.append(c["action"][len("guide:"):])
self.toc_sections = [(f"Version {v['version']}", v["anchor"]) for v in self.versions[:self.detailed]] + \
[(g["label"], g["anchor"]) for g in self.groups]
self.extra_anchors = {g["anchor"] for g in self.groups}
self.body = self.render_whats_new(intro)
def render_whats_new(self, intro: str) -> str:
used = set()
out = [Page(self.name, intro, used).body]
def cards(v):
items = []
for c in v["cards"]:
img = ""
if c["image"]:
size = image_size(SRC / c["image"])
dims = f' width="{size[0]}" height="{size[1]}"' if size else ""
img = (f'<img src="{html.escape(c["image"])}" alt=""{dims} loading="lazy" decoding="async">')
if c.get("clip"): # the clip plays in place of the picture, which stays as its poster
img = (f'<video src="{html.escape(c["clip"])}" poster="{html.escape(c["image"])}"{dims} muted '
f'loop playsinline autoplay preload="none"></video>')
href = card_link(c)
more = (f'<a class="wn-more" href="{html.escape(href)}">'
f'{"Read more" if c["action"].startswith("guide:") else "How it works"}'
f'<span aria-hidden="true"> →</span></a>') if href else ""
items.append(f'<article class="wn-card"><div class="wn-pic">{img}</div><div class="wn-card-body">'
f'<h3>{inline(c["title"], [])}</h3><p>{inline(c["line"], [])}</p>{more}</div></article>')
return f'<div class="wn-cards wn-n{len(items)}">' + "".join(items) + "</div>" if items else ""
def date_html(v):
return f'<time datetime="{html.escape(v["date"])}">{html.escape(v["date"])}</time>' if v["date"] else ""
for n, v in enumerate(self.versions[:self.detailed]):
used.add(v["anchor"])
body = Page(self.name, v["body"], used).body
out.append(
f'<section class="wn-version" id="{v["anchor"]}"><header class="wn-band">'
f'<h2>Version {html.escape(v["version"])}<a class="anchor" href="#{v["anchor"]}" '
f'aria-label="Link to this version">#</a></h2>{date_html(v)}'
+ (f'<p class="wn-tagline">{inline(v["tagline"], [])}</p>' if v["tagline"] else "") + "</header>"
+ cards(v)
+ f'<details class="wn-all"{" open" if n == 0 else ""}><summary>All changes</summary>'
f'<div class="wn-body">{body}</div></details></section>')
if self.groups:
out.append('<p class="wn-earlier">Earlier versions</p>')
for g in self.groups:
used.add(g["anchor"])
items = "".join(f"<li><strong>{inline(t, [])}</strong>: {inline(r, [])}</li>" if t else f"<li>{inline(r, [])}</li>"
for t, r in map(split_highlight, g["highlights"]))
inner = []
for i in g["versions"]:
v = self.versions[i]
used.add(v["anchor"])
inner.append(f'<h3 id="{v["anchor"]}" class="wn-ver">Version {html.escape(v["version"])}'
f'{date_html(v)}</h3>' + Page(self.name, v["body"], used, shift=1).body)
out.append(
f'<section class="wn-group" id="{g["anchor"]}"><header class="wn-band wn-band-small">'
f'<h2>{html.escape(g["label"])}<a class="anchor" href="#{g["anchor"]}" aria-label="Link to these versions">#</a>'
f'</h2></header><ul class="wn-highlights">{items}</ul>'
f'<details class="wn-all"><summary>All changes</summary><div class="wn-body">{"".join(inner)}</div>'
f'</details></section>')
# A link into a folded section opens it.
out.append("<script>(function(){function o(){var h=location.hash.slice(1);if(!h)return;var e=document.getElementById(h);"
"for(var p=e;p;p=p.parentElement)if(p.tagName==='DETAILS')p.open=true;if(e)e.scrollIntoView();}"
"addEventListener('hashchange',o);o();})();</script>")
return "\n".join(out)
# The home page's release area (website/index.html #whats-new, between the whats-new markers): the newest versions
# as cards with their first picture, then the older ones as groups of highlights, all linking into the guide chapter.
HOME = ROOT / "website" / "index.html"
HOME_START, HOME_END = "<!-- whats-new:start", "<!-- whats-new:end -->"
CHANGELOG_URL = "https://github.com/islandmed/SculptForge/blob/main/CHANGELOG.md"
def home_whats_new(page: "WhatsNewPage") -> str:
vs = page.versions[:page.detailed]
out = []
if vs:
lede = vs[0]["tagline"] or vs[0]["version"]
out.append(f' <p class="section-lede">New in {html.escape(vs[0]["version"])}: {inline(lede, [])} '
f'<a href="guide/whats-new.html">Everything that changed</a> · <a href="{CHANGELOG_URL}">changelog</a></p>')
out.append(' <div class="wn-home">')
for v in vs:
titles = [split_highlight(h)[0] for h in v["highlights"] if split_highlight(h)[0]] or [c["title"] for c in v["cards"]]
first = next((c for c in v["cards"] if c["image"]), None)
pic, clip = (first["image"], first.get("clip", "")) if first else ("", "")
img = (f'<div class="wn-pic"><img src="guide/{html.escape(pic)}" alt="" width="600" height="340" loading="lazy" '
f'decoding="async"></div>') if pic else "" # no picture of its own: a text-only card, not filler art
if clip: # the first card's clip plays on the home page too, its picture as the poster
img = (f'<div class="wn-pic"><video src="guide/{html.escape(clip)}" poster="guide/{html.escape(pic)}" width="600" '
f'height="340" muted loop playsinline autoplay></video></div>')
items = "".join(f"<li>{inline(c['title'], [])}</li>" for c in v["cards"]) or \
"".join(f"<li>{inline(r[:1].upper() + r[1:], [])}</li>" for _, r in map(split_highlight, v["highlights"]))
out.append(f' <article class="wn-home-card"><a href="guide/whats-new.html#{v["anchor"]}">{img}'
f'<div class="wn-card-body"><h3>{html.escape(", ".join(titles[:3]) or "Version " + v["version"])} '
f'<small>new in {html.escape(v["version"])}</small></h3>'
+ (f'<p>{inline(v["tagline"], [])}</p>' if v["tagline"] else "")
+ f'<ul>{items}</ul></div></a></article>')
out.append(" </div>")
if page.groups:
out.append(' <div class="wn-home-groups">')
for g in page.groups:
items = "".join(f"<li>{inline(tt, [])}</li>" for tt, _ in map(split_highlight, g["highlights"]) if tt)
out.append(f' <a class="wn-home-group" href="guide/whats-new.html#{g["anchor"]}"><h3>{html.escape(g["label"])}</h3>'
f'<ul>{items}</ul><span>All changes →</span></a>')
out.append(" </div>")
return "\n".join(out)
def write_home(page: "WhatsNewPage", check_only: bool) -> bool:
"""Writes the release area into website/index.html; with CHECK_ONLY, True when it is already up to date. A beta
leaves the home page alone: it keeps showing the stable release until that version ships."""
if project_prerelease():
return True
t = HOME.read_text(encoding="utf-8")
a = t.find(HOME_START)
b = t.find(HOME_END, a)
if a < 0 or b < 0:
sys.exit(f"{HOME}: no {HOME_START} ... {HOME_END} markers in #whats-new")
a = t.index("\n", a) + 1
new = t[:a] + home_whats_new(page) + "\n " + t[b:]
if check_only:
return new == t
HOME.write_text(new, encoding="utf-8")
return True
# ---------------------------------------------------------------------------
# The book
# ---------------------------------------------------------------------------
def load_book():
index = Page("index.md", (SRC / "index.md").read_text(encoding="utf-8"))
chapters, group = [], ""
seen = set()
for line in (SRC / "index.md").read_text(encoding="utf-8").split("\n"):
t = line.strip()
if t.startswith("## "):
group = t[3:].strip()
m = re.match(r"^(?:\d+\.|[-*]) \[([^\]]+)\]\(([^)#]+\.md)\)", t)
if m and m.group(2) not in seen:
seen.add(m.group(2))
path = SRC / m.group(2)
if not path.exists():
sys.exit(f"index.md lists {m.group(2)}, which doesn't exist")
cls = WhatsNewPage if m.group(2) == WHATS_NEW else Page
page = cls(m.group(2), path.read_text(encoding="utf-8"))
chapters.append((group, page))
return index, chapters
def page_html(page: Page, index: Page, chapters, position: int) -> str:
current = page.name
toc = ['<nav class="toc" aria-label="User guide">',
f'<a class="toc-home{" current" if current == "index.md" else ""}" href="index.html">Contents</a>']
group = None
for g, ch in chapters:
if g != group:
if group is not None:
toc.append("</ul>")
toc.append(f'<p class="toc-group">{html.escape(g)}</p><ul>')
group = g
is_cur = ch.name == current
href = ch.name[:-3] + ".html"
current_attr = ' class="current" aria-current="page"' if is_cur else ""
toc.append(f'<li><a href="{href}"{current_attr}>{html.escape(ch.title)}</a>')
if is_cur:
subs = getattr(ch, "toc_sections", None) or [(t, a) for lvl, t, a in ch.headings if lvl == 2]
if subs:
toc.append('<ul class="toc-sections">' + "".join(
f'<li><a href="#{a}">{html.escape(t)}</a></li>' for t, a in subs) + "</ul>")
toc.append("</li>")
toc.append("</ul></nav>")
# Previous / next chapter.
names = ["index.md"] + [c.name for _, c in chapters]
titles = ["Contents"] + [c.title for _, c in chapters]
k = names.index(current)
pager = ['<nav class="pager" aria-label="Previous and next chapter">']
if k > 0:
pager.append(f'<a class="prev" rel="prev" href="{names[k - 1][:-3]}.html"><span>Previous</span>'
f'{html.escape(titles[k - 1])}</a>')
if k + 1 < len(names):
pager.append(f'<a class="next" rel="next" href="{names[k + 1][:-3]}.html"><span>Next</span>'
f'{html.escape(titles[k + 1])}</a>')
pager.append("</nav>")
on_page = getattr(page, "toc_sections", None) or [(t, a) for lvl, t, a in page.headings if lvl == 2]
aside = ""
if len(on_page) >= 3:
aside = ('<aside class="on-page" aria-label="On this page"><p>On this page</p><ul>' +
"".join(f'<li><a href="#{a}">{html.escape(t)}</a></li>' for t, a in on_page) + "</ul></aside>")
title = "SculptForge User Guide" if current == "index.md" else f"{page.title} - SculptForge User Guide"
first_p = re.search(r"<p>(.*?)</p>", page.body, re.S)
desc = re.sub(r"<[^>]+>", "", first_p.group(1)) if first_p else "The SculptForge user guide."
desc = html.escape(html.unescape(desc)[:300], quote=True)
url = SITE + "guide/" + current[:-3] + ".html"
edit = f"https://github.com/islandmed/SculptForge/edit/main/docs/guide/{current}"
return f"""<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{html.escape(title)}</title>
<meta name="description" content="{desc}">
<meta name="theme-color" content="#111114">
<meta name="color-scheme" content="dark">
<link rel="icon" type="image/png" sizes="32x32" href="../img/favicon-32.png?v=7">
<link rel="icon" type="image/png" sizes="64x64" href="../img/favicon-64.png?v=7">
<link rel="apple-touch-icon" href="../img/apple-touch-icon.png?v=7">
<link rel="canonical" href="{url}">
<meta property="og:type" content="article">
<meta property="og:title" content="{html.escape(title)}">
<meta property="og:description" content="{desc}">
<meta property="og:image" content="{SITE}img/social-preview.png?v=5">
<meta property="og:url" content="{url}">
<link rel="stylesheet" href="../style.css?v=19">
<script src="../motion.js?v=12" defer></script>
<script data-goatcounter="https://sculptforge.goatcounter.com/count" async src="https://gc.zgo.at/count.js"></script>
<script src="search-index.js?v={len(chapters)}" defer></script>
</head>
<body class="guide-page" data-prev="{names[k - 1][:-3] + '.html' if k > 0 else ''}" data-next="{names[k + 1][:-3] + '.html' if k + 1 < len(names) else ''}">
<div class="scroll-progress" aria-hidden="true"></div>
<header class="nav">
<div class="wrap nav-inner">
<a class="brand" href="../index.html"><img class="brand-mark" src="../img/bust-mark-44.png" srcset="../img/bust-mark-88.png 2x, ../img/bust-mark-132.png 3x" width="44" height="44" alt=""><span>SculptForge</span></a>
<nav aria-label="Main">
<a href="../index.html#features">Features</a>
<a href="../index.html#demos">Demos</a>
<a href="../brushes.html">Brushes</a>
<a href="index.html" aria-current="page">Guide</a>
<a class="nav-dl" href="../index.html#download">Download</a>
<a class="gh" href="https://discord.gg/gWrYkEmQhH">Discord</a>
<a class="gh" href="https://github.com/islandmed/SculptForge">GitHub</a>
</nav>
</div>
</header>
<div class="wrap guide-layout">
<div class="guide-side">
<button class="toc-toggle" type="button" aria-expanded="false" aria-controls="guide-toc">
<span>Contents</span><span class="toc-current">{html.escape(page.title if current != "index.md" else "SculptForge User Guide")}</span></button>
<div id="guide-toc" class="toc-panel">
<div class="guide-search" role="search">
<input type="search" id="guide-q" placeholder="Search the guide" aria-label="Search the guide" autocomplete="off">
<div class="search-results" id="guide-results" hidden></div>
</div>
{"".join(toc)}
</div>
</div>
<main class="guide-main" id="top">
<article class="guide-article">
{page.body}
</article>
{"".join(pager)}
<p class="guide-meta fine">Also in the app: <strong>Help > User Guide</strong> (<kbd>Shift</kbd>+<kbd>F1</kbd>).
Found a mistake? <a href="{edit}">Edit this page on GitHub</a>.</p>
</main>
{aside}
</div>
<footer class="footer">
<div class="wrap footer-grid">
<div>
<a class="brand" href="../index.html"><img class="brand-mark" src="../img/bust-mark-44.png" srcset="../img/bust-mark-88.png 2x, ../img/bust-mark-132.png 3x" width="32" height="32" alt=""><span>SculptForge</span></a>
<p class="fine">Copyright © 2026 The SculptForge contributors.<br>The SculptForge User Guide is part of
SculptForge, licensed under the <a href="https://github.com/islandmed/SculptForge/blob/main/LICENSE">GNU GPL v3.0 or later</a>.</p>
</div>
<div class="links">
<a href="../performance/">Performance</a>
<a href="index.html">User guide</a>
<a href="../supporters.html">Members</a>
<a href="https://github.com/islandmed/SculptForge">Source code</a>
<a href="https://discord.gg/gWrYkEmQhH">Community Discord</a>
<a href="https://github.com/islandmed/SculptForge/issues">Report a problem</a>
<a href="https://github.com/islandmed/SculptForge/blob/main/docs/ai-services.md">AI services & privacy</a>
</div>
<p class="fine trademarks">SculptForge is an independent project. Product names are trademarks of their respective owners.</p>
</div>
</footer>
</body>
</html>
"""
def redirect_html(target: str) -> str:
"""A page that sends visitors (and search engines) on to a renamed chapter."""
url = SITE + "guide/" + target
return f"""<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Moved - SculptForge User Guide</title>
<meta name="robots" content="noindex">
<link rel="canonical" href="{url}">
<meta http-equiv="refresh" content="0; url={target}">
</head>
<body>
<p>This chapter has moved to <a href="{target}">{url}</a>.</p>
</body>
</html>
"""
# ---------------------------------------------------------------------------
# Checks
# ---------------------------------------------------------------------------
def check(index: Page, chapters) -> list:
problems = []
pages = {"index.md": index}
pages.update({c.name: c for _, c in chapters})
anchors = {name: {a for _, _, a in p.headings} | ({slugify(p.title)} if p.title else set())
| getattr(p, "extra_anchors", set()) for name, p in pages.items()}
wn = pages.get(WHATS_NEW)
if isinstance(wn, WhatsNewPage):
problems += wn.problems
for v in wn.versions:
if not v["date"]:
problems.append(f"{WHATS_NEW}: Version {v['version']} has no ```features block with its date")
for c in v["cards"]:
if not 1 <= len(c["title"].split()) <= 6:
problems.append(f"{WHATS_NEW}: Version {v['version']}: card title '{c['title']}' should be 3-5 words")
if c["image"] and c["image"].startswith("images/wn-") and image_size(SRC / c["image"]) not in (None, (600, 340)):
problems.append(f"{WHATS_NEW}: {c['image']} should be 600x340 (tools/guide/make_images.py --whats-new)")
if v["cards"] and not 1 <= len(v["cards"]) <= 5:
problems.append(f"{WHATS_NEW}: Version {v['version']} has {len(v['cards'])} cards; the window shows 1 to 5")
listed = set(pages)
for f in sorted(SRC.glob("*.md")):
if f.name not in listed:
problems.append(f"{f.name}: not listed in index.md")
for name, p in pages.items():
if not p.title:
problems.append(f"{name}: no '# Title' line")
for lineno, line in enumerate(p.chars.split("\n"), 1):
bad = [ch for ch in line if ord(ch) > 0xFF or (ord(ch) < 0x20 and ch != "\t")]
if bad:
problems.append(f"{name}:{lineno}: characters the app's font can't show: "
+ " ".join(f"U+{ord(ch):04X}" for ch in sorted(set(bad))))
if re.match(r"^#{4,} ", line):
problems.append(f"{name}:{lineno}: only #, ## and ### headings are supported")
for target in p.links:
if re.match(r"^(https?:|mailto:)", target):
continue
path, _, anchor = target.partition("#")
dest = path or name
if dest not in pages:
problems.append(f"{name}: link to {target}: no such chapter")
elif anchor and anchor not in anchors[dest]:
problems.append(f"{name}: link to {target}: no heading with that anchor in {dest}")
for src in p.images:
if not (SRC / src).is_file():
problems.append(f"{name}: image {src} doesn't exist")
for old_name, new_name in REDIRECTS.items():
if new_name[:-5] + ".md" not in pages:
problems.append(f"REDIRECTS: {old_name} points to {new_name}, which isn't a chapter")
if old_name[:-5] + ".md" in pages:
problems.append(f"REDIRECTS: {old_name} is a chapter again; remove the redirect")
used = {src for p in pages.values() for src in p.images}
for img in sorted(f for f in (SRC / "images").rglob("*") if f.is_file()): # also images/<chapter>/*
rel = img.relative_to(SRC).as_posix()
if rel not in used:
problems.append(f"{rel}: not used by any page")
return problems
# ---------------------------------------------------------------------------
# website/supporters.html: the credits on the website, from docs/supporters.txt (the list Help > About shows)
# ---------------------------------------------------------------------------
SUPPORTERS = ROOT / "docs" / "supporters.txt"
SUPPORTERS_PAGE = ROOT / "website" / "supporters.html"
FOUNDING = ROOT / "website" / "founding.json" # the app's compiled copy (Help > About), refreshed each release
# The site's live copy (site lane, no app release): written by ~/Work/.sf/members/onboard.py within a minute or two of
# a payment, from members.csv. When it is there it is the whole truth for this page and support.html:
# {"limit": 100, "taken": 3, "names": [Founding Members' credit names], "members": [every credited name],
# "studios": 0, "updated": "..."}. --app-credits copies it into founding.json + docs/supporters.txt for a release.
LIVE_MEMBERS = ROOT / "website" / "members-live.json"
def live_members():
try:
f = json.loads(LIVE_MEMBERS.read_text(encoding="utf-8"))
except (OSError, ValueError):
return None
if not isinstance(f, dict) or not isinstance(f.get("names"), list) or not isinstance(f.get("members"), list):
return None
return f
def name_list(listed) -> list:
return supporter_names("\n".join(n.replace("\n", " ") for n in listed if isinstance(n, str)))
def supporter_names(text: str) -> list:
"""The same rules as parseSupporters in src/app/Support.h: one name per line, '#' lines and blank lines skipped,
invalid UTF-8, control and invisible formatting characters dropped, spaces trimmed, 40 characters, 2000 names."""
def hidden(c: str) -> bool:
cp = ord(c)
return (cp < 0x20 or 0x7F <= cp <= 0x9F or 0x200B <= cp <= 0x200F or 0x2028 <= cp <= 0x202E
or 0x2060 <= cp <= 0x2069 or cp == 0xFEFF)
names = []
for line in text.split("\n"):
if len(names) >= 2000:
break
if not line.strip(" \t\r") or line.lstrip(" \t\r").startswith("#"):
continue
kept = "".join(c for c in line if not hidden(c) and not 0xD800 <= ord(c) <= 0xDFFF)[:40].strip(" ")
if kept:
names.append(kept)
return names
def supporters_html() -> str:
live = live_members()
if live:
names, fnames = name_list(live["members"]), name_list(live["names"])
else:
raw = SUPPORTERS.read_bytes().decode("utf-8", errors="ignore") if SUPPORTERS.exists() else ""
names = supporter_names(raw)
try:
f = json.loads(FOUNDING.read_text(encoding="utf-8"))
fnames = name_list(f.get("names")) if isinstance(f, dict) and isinstance(f.get("names"), list) else []
except (OSError, ValueError):
fnames = []
if names:
body = ('<ul class="supporters">\n' + "".join(f" <li>{html.escape(n)}</li>\n" for n in names)
+ " </ul>")
else:
body = '<p class="lede">Be the first: <a href="support.html">become a member</a>.</p>'
founding = ""
if fnames: # (parseFoundingMembers in src/app/Support.h: the same names in Help > About)
founding = ('\n <section class="section alt" id="founding">\n <div class="wrap">\n'
' <h2>Founding Members</h2>\n <p>The first 100 members, with our thanks for good.</p>\n'
' <ul class="supporters">\n'
+ "".join(f" <li>{html.escape(n)}</li>\n" for n in fnames)
+ " </ul>\n </div>\n </section>")
return f"""<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Members</title>
<meta name="description" content="The members who keep SculptForge free and open source for everyone.">
<meta name="color-scheme" content="dark light">
<link rel="icon" type="image/png" sizes="32x32" href="img/favicon-32.png?v=7">
<link rel="canonical" href="{SITE}supporters.html">
<link rel="stylesheet" href="style.css?v=18">
<style>
.supporters {{ columns: 3 14em; column-gap: 32px; padding: 0; list-style: none; }}
.supporters li {{ break-inside: avoid; padding: 4px 0; }}
</style>
<!-- Generated by tools/guide/build_site.py from website/members-live.json (else docs/supporters.txt and website/founding.json); edit those, not this one. -->
</head>
<body>
<header class="nav">
<div class="wrap nav-inner">
<a class="brand" href="index.html"><img class="brand-mark" src="img/bust-mark-44.png" srcset="img/bust-mark-88.png 2x, img/bust-mark-132.png 3x" width="44" height="44" alt=""><span>SculptForge</span></a>
<nav aria-label="Main">
<a href="guide/index.html">Guide</a>
<a href="studios.html">Studios</a>
<a class="nav-support" href="support.html">Support</a>
<a class="nav-dl" href="index.html#download">Download</a>
</nav>
</div>
</header>
<main id="top">
<section class="section">
<div class="wrap">
<p class="eyebrow">Credits</p>
<h1>Members</h1>
<p>Thank you to every SculptForge member. The same names are in the app, under Help > About.</p>
{body}
</div>
</section>{founding}
</main>
<footer class="footer">
<div class="wrap footer-grid">
<div class="links">
<a href="performance/">Performance</a>
<a href="index.html">Home</a>
<a href="support.html">Membership</a>
<a href="terms.html">Terms</a>
<a href="jobs.html">Jobs</a>
<a href="https://github.com/islandmed/SculptForge">Source code</a>
</div>
<p class="fine">Copyright © 2026 The SculptForge contributors.</p>
</div>
</footer>
</body>
</html>
"""
def app_credits() -> int:
"""The release step: the app's Help > About lists and the card's fallback count, from the site's live copy."""
live = live_members()
if not live:
print("no website/members-live.json: the app copies stay as they are")
return 0
f = {"limit": int(live.get("limit", 100)), "taken": int(live.get("taken", 0)), "names": name_list(live["names"])}
FOUNDING.write_text(json.dumps(f, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
raw = SUPPORTERS.read_text(encoding="utf-8") if SUPPORTERS.exists() else ""
head = "".join(l + "\n" for l in raw.split("\n") if l.lstrip(" \t\r").startswith("#"))
SUPPORTERS.write_text(head + "".join(n + "\n" for n in name_list(live["members"])), encoding="utf-8")
print(f"founding.json: {f['taken']} of {f['limit']}, {len(f['names'])} names; supporters.txt: {len(live['members'])} names")
return 0
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--out", type=pathlib.Path, default=ROOT / "website" / "guide")
ap.add_argument("--check", action="store_true", help="fail on broken links, missing images or bad characters")
ap.add_argument("--supporters", action="store_true", help="only write website/supporters.html (the site deploy)")
ap.add_argument("--app-credits", action="store_true",
help="copy website/members-live.json into the app's compiled copies (founding.json, docs/supporters.txt)")
args = ap.parse_args()
if args.app_credits:
return app_credits()
if args.supporters:
SUPPORTERS_PAGE.write_text(supporters_html(), encoding="utf-8")
return 0
if args.check and SUPPORTERS_PAGE.exists() and SUPPORTERS_PAGE.read_text(encoding="utf-8") != supporters_html():
print("website/supporters.html is out of date with website/members-live.json / docs/supporters.txt: run tools/guide/build_site.py",
file=sys.stderr)
return 1
index, chapters = load_book()
wn = next((c for _, c in chapters if isinstance(c, WhatsNewPage)), None)
if args.check:
problems = check(index, chapters)
if wn and args.out.resolve() == (ROOT / "website" / "guide").resolve() and not write_home(wn, True):
problems.append("website/index.html: the What's New area is out of date with whats-new.md: run tools/guide/build_site.py")
for p in problems:
print(p, file=sys.stderr)
if problems:
return 1
out = args.out
out.mkdir(parents=True, exist_ok=True)
for old in out.glob("*.html"):
old.unlink()
pages = [index] + [c for _, c in chapters]
for k, page in enumerate(pages):
(out / (page.name[:-3] + ".html")).write_text(page_html(page, index, chapters, k), encoding="utf-8")
for old_name, new_name in REDIRECTS.items():
(out / old_name).write_text(redirect_html(new_name), encoding="utf-8")
images = out / "images"
if images.exists():
shutil.rmtree(images)
shutil.copytree(SRC / "images", images)
# Search: one entry per section.
entries = []
for page in pages:
for anchor, heading, text in page.text_blocks:
entries.append({"p": page.name[:-3] + ".html", "c": page.title, "a": anchor, "h": heading,
"t": re.sub(r"\s+", " ", text)[:4000]})
(out / "search-index.js").write_text("window.GUIDE_INDEX=" + json.dumps(entries, ensure_ascii=False,
separators=(",", ":")) + ";\n",
encoding="utf-8")
# The site's sitemap (website/sitemap.xml, named in website/robots.txt): the homepage, the brushes page and
# every guide page. Only for the real site, not --out folders.
if out.resolve() == (ROOT / "website" / "guide").resolve():
SUPPORTERS_PAGE.write_text(supporters_html(), encoding="utf-8")
if wn:
write_home(wn, False)
urls = [SITE, SITE + "brushes.html", SITE + "press.html",
SITE + "studios.html", SITE + "ai.html", SITE + "support.html", SITE + "terms.html", SITE + "jobs.html", SITE + "queue.html",
SITE + "supporters.html",
SITE + "performance/"] + [f"{SITE}guide/{p.name[:-3]}.html" for p in pages]
(ROOT / "website" / "sitemap.xml").write_text(
'<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n'
+ "".join(f" <url><loc>{html.escape(u)}</loc></url>\n" for u in urls) + "</urlset>\n", encoding="utf-8")
print(f"wrote {len(pages)} pages and {len(list(images.glob('*')))} images to {out}")
return 0
if __name__ == "__main__":
sys.exit(main())