- TypeScript 82.4%
- HTML 11.6%
- JavaScript 3.4%
- CSS 2.6%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .vscode | ||
| packages | ||
| scripts | ||
| tests | ||
| website-designer-design | ||
| websites | ||
| .editorconfig | ||
| .gitignore | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
Wise Eternium
A local Electron WYSIWYG designer and an independent static compiler for Markdown + YAML websites, implementing website-designer-design/. Source files stay authoritative; output is plain static HTML, CSS and assets.
Layout
| Path | What |
|---|---|
packages/core |
Source documents, source-preserving YAML edits, profiles, component schema registry, authoring model, bindings, commands/transactions with multi-file undo, staged saving with a recovery journal, drafts, compatibility scan |
packages/compiler |
Compatibility renderers for the supplied converters (wise-corporate; wise-product with wps/printdna/xmlharbor variants), page shells, output validation, staged output with rollback, reproducible ZIP, the wsd CLI |
packages/app |
Electron app: main process, narrow preload bridge, isolated preview protocol, overlay (Design mode only), renderer UI, build worker |
tests |
Round-trip, transaction, recovery, compiler and output tests; byte-identity against a supplied site's dist/ |
scripts |
Build, icon-table extraction, fidelity comparison, Electron smoke run |
Use
npm install # npm 11: electron/esbuild install scripts are pre-approved in package.json
npm run build
npm test
node packages/compiler/dist/cli.cjs scan ../webs/web
node packages/compiler/dist/cli.cjs build ../webs/wisesourcery-web --out /tmp/out
node packages/compiler/dist/cli.cjs sites websites # a sites root: its sites and shared templates
node packages/compiler/dist/cli.cjs build websites # every site, each into its own dist/
npx electron packages/app/dist/main.cjs [--open=<site or sites root folder>]
npm start and npm run smoke go through scripts/electron.mjs, which clears
ELECTRON_RUN_AS_NODE (VS Code sets it for its child processes).
npm run smoke:sites drives the app through a copy of websites/ (set WSD_SMOKE_ROOT for another).
Several sites in one folder (a sites root)
One folder can hold several sites, each with its own design. Its eternium.yaml lists them;
each site is an ordinary project folder (content/, assets/, designer.yaml), and
templates/ holds designs that several sites share. websites/ is one:
websites/
eternium.yaml the sites, and where the shared templates are
templates/wise-corporate/template.html the company design, used by main-web and wisesourcery-web
templates/wise-product/template.html extends wise-corporate: the product pages' design
main-web/ designer.yaml: template: ../templates/wise-corporate/template.html
wisesourcery-web/ the same
wps-web/ designer.yaml: template: ../templates/wise-product/template.html, repoRoot: ../../../wps
printdna-web/ template.html (its own) extends wise-product: PrintDNA's colours; repoRoot: ../../../printdna
# eternium.yaml
format: wise-sites
formatVersion: 1
name: Wise Global Solutions websites # optional; default: the folder's name
templates: templates # optional; this is the default
sites: # optional; default: every folder here with a content/ folder
- main-web
- wisesourcery-web
- A shared template is
templates/<name>/template.html, an editable design like any other. A site uses it withtemplate: ../templates/<name>/template.htmlin itsdesigner.yaml: the site is drawn by that one file, and editing the design from any site using it (Design space, or the file itself) changes all of them; Save writes it intemplates/. A template path may leave the site only into the sites root it is in (the nearest folder above witheternium.yaml, up to three levels). - Its own template is
template: template.html, as for a site standing alone. - A template can extend another (below), so a design that is a variation of another holds only the variation: wise-product is the corporate design with the product pages' header, footer, components and about 120 of their own style rules; printdna-web's template is wise-product in PrintDNA's colours, in 90 lines.
repoRootindesigner.yaml(relative to the site) is where repository-relative files are found (borrow, editionmatrixsources); without it, the site's parent folder.--repo-rootand Site → Repository Root… still override it.
In the app, Open Folder… on a sites root shows its sites and shared templates. Opening one
puts a site switcher at the left of the toolbar; File → All Sites in This Root goes back.
New Site… (on that screen, or File → New Site in This Root…) adds a folder and lists it in
eternium.yaml, starting from a shared template (used in place), a copy of a shared template or of
another site's design (its own template.html), or the starter design. A site started from another
site's design takes that site's settings (site.md), renamed, without links to that site's pages,
with the logo and icon files they name. Build → Build All Sites builds every site into its own
output folder: the open one as it is in the editor, the others as saved.
On the command line, build, check, export-zip, scan and convert given a sites root run on
each site (--site <folder> for some), and:
wsd sites websites # list the sites and templates
wsd new-site websites docs-web --name "Docs" --template shared:wise-corporate
wsd new-site websites tools-web --template copy:@wise-product # its own copy of the product design
wsd new-site websites dna2-web --template copy:printdna-web # a copy of printdna-web's template (still extending wise-product)
Templates extending templates
<html data-extends="../wise-corporate/template.html"> (a path from the template's own file) makes a
template a variation of another, which it may in turn extend. The page is the base template,
changed by what the extending one holds:
| In the extending template | Does |
|---|---|
attributes on <html>, <body> |
are set over the base's (<body class="{{page.product}}">) |
<title>, <meta name>, <link rel="icon">, <script data-eternium>, any data-block element in <head> |
replaces the base's in its place |
any other element in <head> |
is added after the base's head |
<style> |
is added after the base's styles: where both set something, it wins |
<style data-replace> |
for each selector it has (per @media), replaces the base's rule whole; an empty rule (.site-head > .wrap {}) takes the base's away |
data-block="header" in <body> |
replaces the base's element with that data-block, wherever it is (data-unwrap to put several elements in its place) |
data-component="hero" in <body> |
replaces the base's hero, or adds a component to the base's data-content |
data-remove on any of these |
takes the base's away (<script data-block="js" data-remove></script>) |
wise-corporate marks its parts data-block="js", "header", "main", "footer" and "script".
The editor keeps where everything is written: a component inherited from the base is edited in
the base (changing every site using it), one the extending template defines in that template; new
components, copies of inherited ones and Theme token changes go in the extending template (a token
set there overrides the base's). A missing base, a template extending itself, or a data-block the
base does not have are reported in Problems. To check that a change to templates leaves pages as
they were, build before and after and run
OLD=<built site> NEW=<built site> LOG=report.txt node scripts/electron.mjs scripts/compare-styles.cjs:
it compares every element's computed style at desktop and phone widths, light and dark.
Distribute
npm run dist # release/win-unpacked/: Wise Eternium.exe and the Electron runtime
electron-builder (config under build in package.json) packs packages/app/dist/ into
resources/app.asar beside the Electron runtime; esbuild has already bundled every dependency, so
nothing else goes in. The folder runs as is on any Windows x64 machine, no Node needed; wrap it in
whatever installer you like. The exe is unsigned. Settings live in
%APPDATA%\Wise Eternium, apart from a development run's. To try the packaged app from a VS Code
terminal, clear ELECTRON_RUN_AS_NODE first, or it starts as plain Node and exits.
VS Code
- F5 → App: main + renderer: starts the
watchtask, launches Electron with the main process under the debugger and attaches to the renderer; breakpoints work in the.tssources. The open a site variant asks for a folder. - Ctrl+Shift+B →
build; Run Test Task →test. Other tasks:watch,typecheck,typecheck: watch,test: current file,site: scan/check/build(diagnostics land in the Problems panel),site: fidelity vs legacy dist,app: smoke run. - Debug configs for the CLI, all tests, the current test file and any script under
tsx. - Snippets for content files: type
wsd-in a.mdfile (wsd-hero,wsd-feature,wsd-cta…).
npx tsx scripts/fidelity.ts ../webs compares output with the Python-built dist/ of each supplied site.
npx tsx scripts/convert-check.ts ../webs converts each one to an editable design in memory and checks its pages draw the same.
Editable designs (format version 2)
A site's whole look is one file, template.html: an ordinary web page with its head, styles,
header and footer, and inside <main data-content> every component once, with example content.
Open it in a browser and you see the whole design. To build a page, Wise Eternium replaces the inside
of <main data-content> with that page's sections, each drawn from its component with the example
replaced by the content. designer.yaml says formatVersion: 2 and template: template.html.
<main data-content>
<section class="hero" data-component="hero" data-label="Hero">
<p class="eyebrow" data-field="eyebrow">Welcome</p>
<h1 data-field="title" data-required>A <b>new</b> site</h1>
<p class="lede" data-field="body">One or two sentences about the site.</p>
<div class="cta-row" data-if="actions">
<a class="btn" data-repeat="actions" href="/contact/">Get in touch</a>
<a class="btn ghost" data-repeat="actions" href="/about/">Learn more</a>
</div>
<style>.hero { padding: 96px 0; }</style>
</section>
</main>
Content is unchanged: a section's layout: hero draws the data-component="hero" element. What a
component holds (the Inspector's fields) is read from its markup, and what a new one starts with is
its example, so there is nothing else to keep in step. A component's own <style> is gathered into
each page's head once. New projects start in this format. Site → Convert to Editable Design (or
wsd convert <site>) turns a legacy corporate or product site into it: the converter's layouts are
written into its template.html with examples. Pages draw the same; build/site.py no longer builds
the site.
| Attribute | What it does |
|---|---|
data-component="hero" |
This element is a component (data-label, data-description, data-category describe it) |
data-field="title" |
Its content is that field: a heading for h1–h6, paragraphs for a div or a <p> holding the body, a picture for <img> ([src, width, height]), a link for <a> ([label, href, class…]), else one line. data-format overrides. Left out when empty, unless data-required |
data-repeat="actions" |
Drawn once per item; siblings repeating the same list are only more examples |
data-if / data-unless |
Drawn only when the field (or expression) holds / does not |
data-class="flip:flip tone" |
A class when its expression holds; a bare name adds its value |
data-attr-id="id" |
An attribute from a field, when it has a value |
data-items |
Where a group's items go; the data-component elements inside it are its items (data-items="product" draws only those) |
data-unwrap |
Only the content, not the element |
data-icon="title" |
The line icon whose word appears in the title |
parts.items, parts.intro, parts.after |
The body cut at its ### headings (tiles, steps) |
data-default-tone="grey", data-choices-tone="white grey band" |
A starting value the example does not show; the choices a field offers |
{{ }} still works anywhere for the few places that need logic (a nav item's current class, a value
inside an attribute): see the reference below.
Site → Edit Design (Ctrl+Shift+D) switches to the Design space, whose canvas is the template as a
page: the header and footer around every component drawn from its example. Click any example text
or picture to change it there (it is written back into template.html, and is what a new one starts
with); set a component's options (tone, flip…) in its Example section (data-default-*). Click an
element on the page or in the Structure tree to edit its tag,
classes and attributes, make it show a field, insert elements, or set its styles at every width or
only at one of the page's breakpoints (written as @media (max-width: …) rules in the component's
own <style>). The Theme tab edits the :root tokens of the page's style sheet. In the Pages space
the canvas edits content in place: click any text to retype it (rich text with a toolbar for a
Markdown body: bold, italic, links, headings, lists), click a picture to replace it, change where a
button goes from the toolbar, and move, duplicate, delete or add sections from the selected
section's toolbar. Each value knows the field it came from, so an edit is written to exactly that
field. Any instance can override tokens for itself (tokens: {--accent: "#c00"}, set on its
outermost element). Every change is an undoable command and is written by Save.
{{ }} reference
{{title}} a value, HTML-escaped {{{html}}} written as it is
{{body|block}} Markdown: block, inline, heading (**bold** → <b>)
{{x|class:"ul":"checks"}} other filters: lower, upper, trim, strip, plain, slug, default:v, join:", ", raw
{{#if x}}…{{else}}…{{/if}} also #unless; #with x as y; #each list (as item) with @index @number @first @last @count
{{> hero}} another component's markup
(helper a "b" 3) eq ne not and or gt lt add len list rest at default concat where
links link pairs image logo split icon cell fence unfenced highlight
codeframe first without table matrix mark trim strip slug plain md
../x @root.x this.0 the enclosing context, the top, an item of a list being iterated
Groups get children (each item's fields plus html, its drawn markup, and item.number/item.count).
Every component also sees site, page and vars. Blocks and elements must nest (an {{#if}} may
not open in one element and close in another), so a template can always be edited visually.