No description
  • TypeScript 82.4%
  • HTML 11.6%
  • JavaScript 3.4%
  • CSS 2.6%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-08 15:52:44 -08:00
.vscode Prep for Linux Migration 2026-11-08 15:52:44 -08:00
packages Prep for Linux Migration 2026-11-08 15:52:44 -08:00
scripts Prep for Linux Migration 2026-11-08 15:52:44 -08:00
tests Prep for Linux Migration 2026-11-08 15:52:44 -08:00
website-designer-design Initial import of Wise Eternium 2026-10-29 14:30:40 -07:00
websites Prep for Linux Migration 2026-11-08 15:52:44 -08:00
.editorconfig Initial import of Wise Eternium 2026-10-29 14:30:40 -07:00
.gitignore Initial import of Wise Eternium 2026-10-29 14:30:40 -07:00
package-lock.json Initial import of Wise Eternium 2026-10-29 14:30:40 -07:00
package.json Prep for Linux Migration 2026-11-08 15:52:44 -08:00
README.md Prep for Linux Migration 2026-11-08 15:52:44 -08:00
tsconfig.json Initial import of Wise Eternium 2026-10-29 14:30:40 -07:00

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 with template: ../templates/<name>/template.html in its designer.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 in templates/. A template path may leave the site only into the sites root it is in (the nearest folder above with eternium.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.
  • repoRoot in designer.yaml (relative to the site) is where repository-relative files are found (borrow, edition matrix sources); without it, the site's parent folder. --repo-root and 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 watch task, launches Electron with the main process under the debugger and attaches to the renderer; breakpoints work in the .ts sources. 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 .md file (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.