Markout, or: how I learned to stop worrying and love the platform

[fcapolini]

When I started researching this project I was firmly in the "HTML is the
PostScript of the Web" camp — an output format, not a language anyone should
be writing by hand. It took me a long time to notice I had been wrong about
which half needed replacing.

We're here because we think the web platform is pretty damn good, and we'd
like to see how far we can push it by extending it rather than replacing it.

That "we" is an invitation, not a company. Right now it's one person and a lot
of measurements; this forum exists so it can be more than that.

Markout is an HTML extension. Not a framework that compiles to HTML — the
page stays a page. <:define> is a tag. ${…} sits in the markup where the
value goes. There's no package.json, no bundler config, and no build step you
have to run before a browser will accept the file. The whole language surface
this repo's benchmark app uses is three tags and eight attribute forms;
everything else in those files is HTML you already know.

Three deliveries, and they're genuinely different things:

• Served — Node in the request path, the page arrives with its content in
  the markup.
• markout build — compiles and stops; values resolve in the browser, the
  same shape as an SPA.
• markout prerender — renders once at build time and freezes it, which is
  right for a documentation site and wrong for anything whose content changes
  without a redeploy.

What we're not claiming

Markout is 0.6.1. It's younger than everything it gets compared to, it has no
ecosystem, and there are columns where it loses badly — the benchmark in this
repo records them rather than omitting them, and
#38 is the thread about
exactly that.

We'd rather be argued with on numbers than agreed with on vibes. If something
here is wrong, the fastest way to help is to say which measurement you don't
believe and why.

Where to start

• The benchmark — one
  app written six times, driven through the same interactions in a real
  Chromium, weighed as well as timed. The full tables and the methodology are
  in packages/cli/bench.
• Design notes
  — what was chosen, what was rejected, and why. These are the interesting
  files.
• POSITIONING.md
  — who this is for, argued honestly, including who it isn't for.

What belongs where

• Q&A — "how do I…", "why does this happen". No question is too basic;
  there's no Stack Overflow answer for this yet, and that's on us.
• Ideas — features, RFCs, anything with an open design question. Several
  design docs have a ## Open section that would be better as a thread.
• Show and tell — anything you built, however small. Genuinely wanted: we
  have very little idea yet what people reach for first.
• General — everything else, including "I tried this and bounced off it,
  here's where". That one is worth more than a star.