Long-form writing
Notes, explainers, and blog posts: the post header, sidenotes, margin figures, footnotes, theorem environments, and collapsible detail.
Experimental May change in any minor version before 1.0.
In this chapter 15 pages
Post header
Example note: the Hodge Laplacian, drawn
A worked example on one triangle.
<PostHeader
title="Example note: the Hodge Laplacian, drawn"
lede="A worked example on one triangle."
date="2026-09-14"
minutes={6}
tags={["Topology"]}
/>The title is set like a paper's, so a site's posts and papers read as one series. The date prints in full, as "14 September 2026"; pass locale for another language. In an <Article>, give it slot="header" and it lines up with the text. Its title sizes to the header's own width, so the header takes its width from where it sits; in a box that shrinks to fit its content, give it a width. The blog post pattern shows the whole page.
An entry without a date
A project page or a section has no date. Leave out date, give the facts for the meta line in meta, and put actions in the default slot, under the tags. stop ends the title in the tomato full stop for a page that is a section.
Example project
A plotting library for simplicial data.
<PostHeader title="Example project" lede="..." meta={["Open source", "2025"]} tags={["Python"]}>
<p><a class="ply-button ply-button--sm" href="https://github.com/...">Source</a></p>
</PostHeader>Math in text from data
M sets one formula in markup. A summary, an abstract, or a caption that is written in front matter or a JSON file has no markup to put it in, so Tex takes the whole text: each $...$ renders through KaTeX at build time, *italic*, **bold**, and ***both*** become em and strong, and the rest is written out as it is. Each formula stays on one line, since a short formula split after its operator reads wrong. html passes trusted inline HTML through, for a caption.
A -simplex has faces in an -complex, so a pass over all cells costs one sweep.
<p><Tex text={paper.tldr} /></p>
<p><Tex text={String.raw`Sums over $n imes d$ cells, in *one* pass.`} /></p>Tex does not load KaTeX's stylesheet. M and Equation import it as a linked stylesheet, which holds the first paint until it arrives. A page that cares about its first paint puts KatexAssets in its head when hasMath says its text has some. That writes the stylesheet inline and preloads the two faces nearly every formula uses, Main-Regular and Math-Italic. The rarer faces load when a formula draws them; preload="all" preloads all five. This page does so. Write a literal dollar sign as \$, and in a YAML front matter field put text with backslashes in single quotes.
import { KatexAssets, Tex, hasMath } from "@dario-loi/polytope/astro";
<head>{hasMath(paper.tldr, paper.abstract) && <KatexAssets />}</head>emphasis(text) and plain(text) from the same module turn the markers into markup or drop them, for a search description or a feed.
Theorem environments
<Env kind="definition" num="2.1" name="Simplicial complex">...</Env>
<Env kind="theorem" num="2.2">...</Env>
<Env kind="proof">...</Env>Kinds: definition, theorem, lemma, proposition, corollary, remark, example, proof. Theorems and lemmas set their body in italics, as print does; definitions sit on the wall gray; proofs end with a tomato box.
Sidenotes
A sidenote keeps a remark next to the sentence it belongs to.1When the page has room after the text, the note sits there, in the margin. On a narrow screen it drops below the line. Use them for asides a curious reader wants and a hurried one can skip.
<p>A sentence.<Sidenote n={1}>The aside.</Sidenote> More text.</p>In the margin
A small figure, table, or code block can sit in the same margin as the sidenotes, beside the paragraph after it. Place it before that paragraph and give it .ply-margin, or pass margin to <Figure>. Where the margin is closed, it stays in the text, above that paragraph.
<Figure margin num={1}>
<img src={sketch.src} alt="A filled triangle with oriented edges." />
<Fragment slot="caption">A 2-cell and its three oriented edges.</Fragment>
</Figure>
<p>The paragraph it sits beside.</p>Keep margin blocks small: 14rem wide is room for a sketch, a short table, or a few lines of code. Anything larger belongs in the text.
Collapsible detail
Derivation of the update rule
Long derivations, extra tables, and setup details go here, closed by default, so the main argument reads straight through.
<details class="ply-details">
<summary>Derivation of the update rule</summary>
<p>...</p>
</details>Emphasis
Inside .ply-prose, emphasis is set in type alone. Italic is the true italic face, one step heavier than the body so it reads as a change of voice. Bold stays bold, and both together are bold italic. Use italic for a term being introduced or a word the sentence stresses, and bold for what a reader must not miss.
<p>A <em>sheaf</em> assigns data to open sets. <strong>Read this first.</strong></p>Quotes
Quotes keep a thin rule and a larger size, and the source goes underneath.Source, year
Footnotes
For references that should not interrupt the line, use a numbered list in .ply-footnotes at the end of the article.