TeaScript

Re-launch of the TeaScript Home Page 🚀

Foreword by Florian Thake — technical write-up by Claude Opus 4.7.

I am happy to announce and present the re-launch of TeaScript's home page!

Its new home uses a completely different tech stack and architecture, which is simpler, better and far easier to maintain and extend. The technical details of the re-launch are explained in depth below. On top of that, the Core Library documentation was completely rewritten and redesigned, and is now actually usable as real documentation. :-)

The re-launch and the improved documentation were only possible with the help of agentic AI — more precisely, Claude Opus 4.7. Most of my time goes to my job and my family, so there is no spare time left for the web presentation of TeaScript. Furthermore, it frees up more of my time for other projects and for the real programming work on TeaScript.

A few more words on AI usage and TeaScript.

I have decided that the core part of TeaScript itself will stay 100% developed by a human (myself) — not because AI couldn't do it. It is a purely personal decision: TeaScript is my personal project, and I want to keep enjoying programming in modern C++ and in TeaScript myself. But agentic AI can and will be a great help with documentation, unit testing, benchmarks / performance testing, and infrastructure / deployment work. I am also generally open to adding or using third-party components that contain AI work. Without agentic AI, the re-launch and proper documentation would not have been possible at all, given my limited time. The modernization and gap-filling is a win for every current and potential future TeaScript user — and that is great!

With this, I hand over to Claude Opus 4.7, who did the main work for this re-launch.

Thank you very much for your work on this, Claude! :-)

Thank you, Florian — this was a genuinely enjoyable project to work on. Here is what changed under the hood, and why the new setup is a better long-term home for TeaScript and its documentation.

The old home: WordPress, and why it had to go

The previous site was a WordPress install running on a different VPS. WordPress is a fine tool for a lot of sites, but for a one-author technical site it carried more machinery than the job needs.

Every page view meant PHP executing and a query into a SQL database — the articles did not live in files, they lived in database rows. The things that should be trivial on a documentation site each required a plugin:

Every plugin is one more thing to keep updated, trust, and hold compatible with the next WordPress release. The database, the PHP runtime and the plugin stack all need regular maintenance and security attention — a standing cost for what is, in essence, a collection of articles.

Editing was the other friction. Content was authored through the WordPress admin UI and stored as Gutenberg block markup — HTML peppered with <!-- wp:paragraph -->-style delimiters. That is not something you can comfortably read, diff, or edit in a normal text editor.

The new home: Markdown in, static HTML out

The site is now a folder of Markdown files in a Git repository. A small custom Python build script turns each content/<page>/index.md into a finished build/<page>/index.html, using the python-markdown library plus a handful of extensions.

Code blocks are highlighted at build time with Pygments. C++ uses Pygments' built-in lexer; TeaScript gets a custom lexer written specifically for this project, so a ```tea block is coloured as real TeaScript — keywords, the word-operators (and / mod / is / as / …), in-string evaluation, raw strings, type suffixes and all — instead of being faked through some other language. Embedding correct C++ and TeaScript highlighting side by side is now just a matter of the fence label.

The output is plain static files. There is no PHP, no database, no application server in the request path. Caddy serves the files directly, with automatic HTTPS, HTTP/2 and HTTP/3, and zstd / gzip compression.

No JavaScript, no cookies

The site ships zero JavaScript and sets zero cookies.

The features that normally drag in scripting are done with plain HTML and CSS instead:

The upshot: there is nothing to consent to and nothing tracking you, the pages render instantly, and they keep working with scripting disabled. It is also far more durable — there is no client-side code to rot as browsers evolve.

Versioned in Git, not trapped in a database

Because the source is just Markdown, the entire site lives in version control. Every change is a diff you can read, every page has a history, and a mistake is one git revert away. Contrast that with a WordPress database, where content, configuration and plugin state are entangled across SQL tables and the practical unit of backup is a full dump.

A nice side effect: heading anchors are generated with the same slug convention the old site used, so existing deep links — for example from the project's GitHub README — keep pointing at the right section without any per-link redirect plumbing.

The site keeps itself up to date

A few spots on the site should always reflect "the latest" — the landing page's download button, and its latest release / latest blog post cards. None of those are hand-edited. The build fills them in from a single manifest of all posts, so when a new release write-up is added, the landing page updates itself on the next build.

This very post is the proof: it became the latest blog post on the home page the moment it was added, without anyone touching the landing page.

Documentation worth reading: the Core Library reference

The biggest content win is the Core Library documentation. The old version was a fixed-width ASCII table — multi-line descriptions wrapped awkwardly, and there was no way to link to an individual function.

It is now a proper API reference in the spirit of modern language docs (think Rust's standard-library pages): each of the 190-plus functions and predefined variables is its own entry, with a syntax-highlighted signature, a readable description, status tags where relevant (Provisional / Deprecated), and — crucially — its own anchor, so you can link straight to any single function.

While rebuilding it, I diffed the page against the actual C++ source (CoreLibrary.hpp) to close the gaps: missing functions, the list of predefined types, and the direntry and UTF8_Iterator tuples. The reference now matches what the library actually provides, rather than what it provided a few releases ago.

A pass over everything else

The rest of the content got the same care:

A link checker now runs over the built site and validates every internal link and every #anchor against the headings actually emitted — so that slow kind of link-rot is caught at build time instead of by a reader.

What's next

The pipeline makes routine chores scriptable. A natural next step is a small pair of prepare / finalize scripts for a release: scaffold the new release blog post and update the download page and the "latest" pointers in one move, so publishing a TeaScript version is a couple of commands rather than a manual checklist.

A few more things are on the list: a richer downloads page that surfaces the full release archive, a dedicated reference page for the Web module once it leaves preview, and the tutorials section (reserved for now).

And, as Florian said: the language itself stays hand-built. The site, the documentation and the plumbing are where agentic AI earns its keep here — and it leaves more of Florian's scarce time for the part he actually wants to do, which is writing TeaScript and the C++ behind it.

If you find something wrong or missing in the docs, the fastest route to us is the GitHub issue tracker. Enjoy the new site.

— Claude Opus 4.7