Technical Manual sections
Reference āŗ Technical Manual āŗ Rendering
Rendering turns the files of an app into HTML in three steps: the loader compiles each file into a JavaScript module, kitten.html renders what the module returns, and the page route wraps the result in a page shell.
The loader script compiles each of Kittenās file types (e.g., .page.js, .component.ts, and .page.md) into a JavaScript module. For Markdown pages, Markdown fragments, and HTML fragments, the loader (src/lib/loader.ts) calls the markdownModule() function (src/lib/markdownModule.ts), which parses the front matter of a Markdown page as YAML.
src/lib/html.ts implements kitten.html, the tagged template that every page, component, and fragment returns. It is Kittenās merged and modified copy of xhtm (which parses the template into a tree) and vhtml (which renders the tree as HTML). It also renders <markdown> blocks, and it returns a promise when one of the values it interpolates is a promise, an async component, or a stateful component.
kitten.html returns a frozen array of strings that Kitten marks as markup (src/lib/markup.ts). Two WeakSets record which values are markup and which are trusted (kitten.markAsTrusted()), so a plain string can never pass for either. Kitten checks each interpolated value against the place it lands in:
text,
an attribute value,
a JavaScript-valued attribute,
a URL,
a script,
a prop of a component (where Kitten refuses markup),
attribute position, or
tag position.
(The Interpolated values section of the reference lists these rules from an authorās point of view.)
src/lib/markdown.ts configures Kittenās MarkdownIt instance (kitten.md) and its plugins:
heading anchors and, for Markdown pages and
<markdown heading-links>blocks, heading links (markdown-it-anchor),bracketed spans (markdown-it-bracketed-spans),
attributes (markdown-it-attrs),
footnotes (markdown-it-footnote),
image figures (markdown-it-image-figures),
inserted, marked, subscript, and superscript text (markdown-it-ins, markdown-it-mark, markdown-it-sub, and markdown-it-sup),
syntax highlighting (markdown-it-highlightjs),
the table of contents (markdown-it-toc-done-right), and
task lists (markdown-it-task-checkbox).
Both the loader and the main process use it.
PageRoute wraps what a page returns in a full HTML document. It chooses the client-side libraries to load from the attributes of the pageās <page> tag (a live page always loads htmx and its idiomorph and WebSocket extensions, and a page that uses hx-boost always loads htmx), and always loads kitten-1.js, which configures htmx and defines the browserās kitten global. The libraries come from lib/ and node_modules/, and the build copies them into /š±/library/ (see Build and release). In production, Kitten serves the minified versions of htmx, the idiomorph extension, Kittenās Alpine.js module, and Water.css (kitten.libraries in src/lib/globals.ts).
In development, the page shell also loads the hot reload script, and Kitten runs the html-validate validator over the page and adds its results to the page (src/routes/lib/validator.ts).
Source code:
The Glossary in the reference defines the kinds of pages you author in Kitten. They differ in when Kitten renders them:
A static page (an .html or .htm file) is not rendered.
StaticRouteserves it as it is (in development, with the hot reload script).A dynamic page (a .page.js, .page.ts, or .page.md file) is rendered on every request. A dynamic page is either a stateless page or a stateful page (see Page routes).
A live page is a dynamic page that also streams updates to the browser over its WebSocket connection after Kitten renders it (see Live pages).
Cached pages, which would be dynamic pages that Kitten renders only once, are not implemented yet (see Cached pages).
The dynamic page is the default page type in Kitten.
All you have to do to create a dynamic page is to export a default function that returns kitten.html.
For example, the following displays the current date and time every time the page is reloaded:
export default () => kitten.html`
<h1>${new Date()}</h1>
`
Dynamic pages are rendered again (have their default export, or their html() method, called and the result sent to the browser) on every GET request.
Thatās all there is to dynamic pages.
All HTTP routes ā e.g., GET, POST, etc. ā are also rendered on every hit. If you want to cache their results, you have to implement your own caching mechanism. (Which you could do using Kittenās built-in database support.)
Not implemented yet, see issue #365.
Cached pages are dynamic pages that export a special flag that makes Kitten render the page only the first time it is hit:
// Cache response until server restarts.
export const cache = true
This will make Kitten cache the page until the server restarts (which will happen, for example, if Kitten or the app is updated).
Optionally, you can also set the cache value to the time, in minutes, that you want content cached for:
// Cache response for a day.
export const cache = 24 /* hours */ * 60 /* minutes */