Diagrams
A picture is not a code sample, and specular does not ship a diagram module. The docs project depends on the tool itself and hands the result to a mount specular already has.
An ascent component is illustration. A DOM element is illustrationDom: the site SSRs a
placeholder, and the client passes the live element to a Mounter. exampleDom stays the
sample, with a source panel. Palette, width, and breakpoints are arguments to the tool, not
theme tokens and not specular CSS.
The figures below are mermoid
0.2.0, a docs-only dependency of these pages. That release parses flowchart, stateDiagram-v2,
classDiagram, erDiagram, and sequenceDiagram. Mermaid("...") parses the diagram at
compile time, so a broken figure fails the build before it reaches a reader. There is no
relational schema in specular, so this page does not draw an erDiagram.
// the docs project, never a published module
libraryDependencies += "rocks.earlyeffect" %%% "mermoid-ascent" % "0.2.0"
illustration { MermoidAscent.diagram(Mermaid("flowchart LR
a --> b")) }
illustrationDom("poster")
// client:
Mounter.sync(el => /* the tool writes into el */)
A fenced mermaid block inside prose is a code block. The markdown renderer does not paint it.
A DocSpec becomes a test and a page
One DocPage is read twice. DocSpecSuite lives on Test and DocTestInterpreter turns each
.assert into a zio-test case. DocsSite lists the same page, and SiteBuilder SSR-renders
it. sbt test does not build the HTML, and specularSite does not run the suite.
Read twice, not stepped through
DocPage has no status field. Source, asserted, and rendered are the two reads of that source:
sbt test asserts what carries .assert, and specularSite renders the tree either way. An
example with no assertion still becomes HTML.
The page algebra
DocSpec is the page. DocPage holds a title and DocNode children. Example is a
sample. Illustration is a region with no source panel. SourceCite is a definition that
already exists in this build. Section nests more nodes. Prose, ValueExample,
FailExample, CrashExample, and DomExample are the other DocNodes. They are not in
the picture.
Who runs the page
A reader, sbt test, and specularSite. The test folds the page into assertions. The site
build folds the same page into HTML. Neither one calls the other.
This figure runs in your browser; enable JavaScript to see it.