src

Sitez itself: a Vite plugin, and the stages a site goes through on its way to dist/. Each stage gets a file here, or a folder once it needs more than one, as its step in plan.md starts.

plugin.ts is sitez(), the plugin a site adds to its vite.config.js, which has no options.
discover.ts decides which files are pages, at which URLs, which files in code/ are elements, and which names are mistakes.
metadata.ts is what a page knows about itself, the site and every page.
head.ts is code/index.html: its checks, and the head Sitez writes for each page.
text.ts turns a Markz page into HTML, its elements written around what their templates write.
data.ts reads the JSON in data/ that an element's data attribute names.
warnings.ts is how Markz's warnings reach the author, with the file, the line, and what to write instead.
links.ts is where a link in text goes, and whether it's there.
browser.ts finds the elements a page uses that ship CSS or behavior, from its HTML.
vite.ts is what the plugin's parts share: the site's modules in Vite's module runner, each part of an element file as a module, and the import rule between build code and browser code.
render.ts is what Sitez adds to a template's scope, and puts a page in its frame.
site.ts is what build and dev share: reading the site, and rendering one page or redirect.
redirects.ts reads the old URLs a page lists, and checks that each is free.
bundle.ts builds what the browser downloads besides the HTML: the stylesheets index.html links, the elements' CSS, and the script of the elements with behavior.
build.ts is the plugin's build half: it renders every page, writes dist/, and makes vp preview serve it as a static host would.
report.ts is what build prints: what each page costs to send and to build.
dev.ts is the plugin's dev server half, rendering each page as it's asked for.
elementz/ is the element layer: the element file, rendering elements, html and the browser's runtime. It imports nothing from the rest of Sitez.
errors.ts is how a mistake in a site becomes a message naming the file and what to change.

Folders

elementz/
The element layer: one @name.html file, read into its parts, rendered at build time and run in the browser (elementz.md). Nothing here imports the rest of Sitez, so the folder can become a package of its own once a second host, such as Pagez, wants it. Sitez is its host, and gives it modules through Vite and data from data/.

Code

browser.test.ts
Which elements a page's HTML uses that ship CSS or behavior. A tag counts only when it's a real start tag of an element with a <style> or a <script>. That script imports a library by URL inside its setup, never at the top.
browser.ts
Which elements a page uses that send something to the browser: CSS from a top-level <style>, or behavior from a top-level <script>. A page's finished HTML is scanned for its tags, and an element with neither part ships nothing. A page with no behavior loads no JavaScript, and one with no element CSS links no element stylesheet.
build.ts
vp build, for a site: every page rendered to complete HTML in dist/, with a page at each redirect, and public/ copied beside them. The site is read once (site.ts), then pages render concurrently, and the stylesheets, the elements' CSS and the script for elements with behavior are built from what they rendered. Nothing is written until everything has built. Markz's warnings and the report print through Vite's logger.
bundle.ts
What the browser downloads besides the HTML, built by Rolldown once every page has rendered, since only then is it known which elements the pages use. A site's stylesheets are the ones code/index.html links, and one more for its elements' CSS. Its script is the behavior of its elements, at most one. Each is small, so one file, cached by the first page and reused by every other, costs less than a split that saves a few bytes per page. Every file's name carries a content hash, so a new deploy is never served from a stale cache.
data.ts
What a data attribute names (rule 5). {@card-grid data="talks.json"} reads data/talks.json and hands the element what it parses to. The path is checked like a link. A file that isn't there, one outside data/ and one that isn't JSON each fail naming the line, rather than giving the element nothing. JSON is the only format, and CSV is parked (design.md).
dev.test.ts
vp dev on a copy of the blog, with Sitez in its config: how it serves pages, and what the browser is told when a file changes.
dev.ts
vp dev, for a site: every page, drafts included, rendered when it's asked for, by the same code as build (site.ts), so a page can't look one way here and another in dist/. The site is read again for every page, so a new or deleted file is a new or missing URL at once, with nothing to restart. A change reloads the page, except to CSS, which Vite replaces in place. A mistake shows in the browser as the message build would print, and the page reloads when it's fixed.
discover.ts
Which files are pages, and at which URL (rule 1), and which files in code/ are elements. Every .md in text/ is a page, and nothing in code/ is. A page's path, less the extension, is its URL, and index is its folder's own. A file or folder whose name starts with . or _ is skipped in every folder, since a site's tools leave the first and the author marks the second.
errors.ts
A mistake in the site, as opposed to a bug in Sitez. Every failure a user can cause is one of these, and it names the file and says what to change. The build never guesses its way past one. It prints one without a stack trace, and anything else thrown is a Sitez bug and keeps its stack. The class is elementz's (elementz/errors.ts), since an element file's mistakes are too.
head.test.ts
What fails code/index.html, each with the line to add or remove, and what Sitez writes in a page's head: the page's title and description in place of the frame's, and the tags that follow.
head.ts
code/index.html and Sitez share each page's head, and each tag has one owner (rule 2). The frame writes lang, charset, viewport, its stylesheets and everything else the site chooses. Sitez puts the page's title and description in place of the frame's, and writes the canonical link and the seven Open Graph and Twitter tags that follow from them and url in site.md. Those repeat two values with no choice in them. A page that sets neither title nor description keeps the frame's own, and so do its social tags.
links.ts
Where a link in text goes, and whether it's there (rule 4). Text links to files, as it does on GitHub, and Sitez turns each into the URL the site serves it at. A page's .md becomes the page's URL, a file in public/ its path, and any other file in the repo its page on GitHub. A site link (/about) is Markz's form for a URL on this site, and is checked the same way. A full URL is another site's, and is never checked.
metadata.ts
What elements know about a page, the site and every page (rule 5). A page's metadata is its Markz block and its url, and nothing else. Sitez reads title, description, draft and redirects from it, and fills in none of them from the text. title and description go in the head (head.ts), draft keeps the page out of the build, and redirects write pages (design.md).
plugin.ts
What a site adds to its vite.config.js, with no options: sitez() from @amitkaps/sitez/vite. The plugin is the site's dev, build and preview, under Vite's own commands. dev.ts serves pages through Vite's dev server, and build.ts renders them and has Vite bundle the CSS and the script. vp preview serves what build wrote.
redirects.test.ts
Which old URLs a page can list, and the failures that name the page listing one. The page Sitez writes at each is in the example blog's snapshots.
redirects.ts
A page that moved lists the URLs it used to have under redirects, and Sitez writes a small page at each one that sends the browser on (docs/design.md#metadata). A page's URL is still its file's path (rule 2). A redirect only points old addresses at it, so a site can move its files without breaking links from elsewhere.
render.test.ts
The page goes where the frame keeps its place, exactly as it was rendered.
render.ts
A page becomes one complete HTML document, with every element in it rendered (rule 5). An element's template gets what Sitez adds to its scope, page, pages and site, beside its own attrs and html (elementz/elements.ts). The frame is in head.ts, and site.ts puts the parts together.
report.ts
What build prints when it's done (promise 5): each page's cost to send, gzipped, and to build, so a page that grows heavy or slow is visible where the cost is. What pages share is one common row, since the browser downloads it once. That's the stylesheets, and the script for the pages whose notes name an element with behavior. A site with neither has no such row. The last line is the whole build, its elements with behavior and the version of Sitez that ran.
site.ts
What vp build and vp dev share, so they can't render a page differently. A run reads the site, then renders one page into the parts of its document. Reading the site means its metadata, its pages and every page's metadata, which each page gets as pages and every link is checked against.
text.test.ts
Markz's HTML with its links rewritten, its elements written around what their templates write and its raw blocks written as they are. A fake render shows what each element is called with.
text.ts
A text page is Markz's own HTML, with the inside of each element that has a file replaced by what its template writes (rule 5). Links are written as the URLs the site serves (rule 4). Everything else comes out exactly as Markz writes it, text, attributes and raw HTML included.
vite.test.ts
A site's import "@amitkaps/sitez" gets html, whose templates the build renders. Only build code gets it, and an element's browser <script> that imports it fails. Each part of an element file is a module, with the file's own lines. Vite resolves every other import as Node does, from the site's own node_modules.
vite.ts
What the plugin's parts share: the link from a site's files to Vite's module runner, an element file's parts as modules, and the naming of a site's files in Vite's errors. Pages render through the runner, so the site's modules run from where they are and import.meta.url still points at them. The Markz site's Quality page reads its test cases relative to its own file. A site's imports resolve as Node's do, from its own node_modules.
warnings.ts
Syntax Markz kept as text or read in its own way, such as *emphasis* or an element with no closing line. The page still builds, so a warning never fails build; it is printed with the file and line, so the author can write the supported form instead.

No prose yet

discover.test.ts · links.test.ts · metadata.test.ts · report.test.ts