@rettangoli/sites 0.2.7 → 1.0.0-rc10

package/README.md

@@ -1,133 +1,241 @@
 # Rettangoli Sites
 
-A static site generator using Markdown and YAML.
+`@rettangoli/sites` is the static-site engine used by Rettangoli. It renders pages from YAML and Markdown into `_site/`, with support for templates, partials, global data, collections, and watch mode.
+
+It can run directly with `bunx rtgl`, so a site-level `package.json` is optional.
 
 ## Quick Start
 
 ```bash
-# Create a new site from template
-bunx rtgl sites init my-site                   # Uses 'default' template
-bunx rtgl sites init my-site -t default        # Explicit template name
+# scaffold
+bunx rtgl sites init my-site
 
-# Install and build
+# run
 cd my-site
-bun install
-bun run build
+bunx rtgl sites build
 ```
 
-## Project Structure
+## Package Contract
 
-```
+```text
 my-site/
-├── pages/           # Content (YAML and Markdown)
-├── templates/       # Page layouts
-├── partials/        # Reusable components
-├── data/            # Global data files
-├── static/          # Static assets
-├── sites.config.js  # Optional config
-├── package.json
-└── _site/           # Generated output
+  pages/           # YAML or Markdown pages (with optional frontmatter)
+  templates/       # YAML templates
+  partials/        # YAML partials
+  data/            # Global YAML data
+  static/          # Static assets copied to _site/
+  sites.config.yaml # Optional site settings
+  _site/           # Generated output
 ```
 
-## Pages
+## What It Supports
 
-**YAML page:**
-```yaml
----
-template: base
-title: Home
----
-- h1: Welcome
-- p: Hello world
-```
+- YAML pages rendered through `jempl` + `yahtml`
+- Markdown pages rendered through `markdown-it` + Shiki (default `rtglMarkdown`)
+- Frontmatter (`template`, `tags`, arbitrary page metadata)
+- Global data (`data/*.yaml`) merged with page frontmatter
+- Collections built from page tags
+- `$if`, `$for`, `$partial`, template functions
+- Static file copying from `static/` to `_site/`
+- Watch mode with local dev server + websocket reload
 
-**Markdown page:**
-```markdown
----
-template: base
-title: About
----
-# About Us
+## Site Config
 
-Content in **markdown**.
+Use `sites.config.yaml` (or `sites.config.yml`) with top-level `markdownit` for supported settings.
+Legacy key `markdown` is still accepted as an alias.
+
+```yaml
+markdownit:
+  preset: default
+  html: true
+  xhtmlOut: false
+  linkify: true
+  typographer: false
+  breaks: false
+  langPrefix: language-
+  quotes: "\u201c\u201d\u2018\u2019"
+  maxNesting: 100
+  shiki:
+    enabled: true
+    theme: slack-dark
+  codePreview:
+    enabled: false
+    showSource: true
+    theme: slack-dark
+  headingAnchors:
+    enabled: true
+    slugMode: unicode
+    wrap: true
+    fallback: section
+build:
+  keepMarkdownFiles: false
+imports:
+  templates:
+    base: https://example.com/templates/base.yaml
+    docs: https://example.com/templates/docs.yaml
+  partials:
+    docs/nav: https://example.com/partials/docs-nav.yaml
 ```
 
-## Syntax
+In the default starter template, CDN runtime scripts are controlled via `data/site.yaml`:
 
 ```yaml
-# Element with class and id
-- div.container#main:
-    - h1: Title
-
-# Attributes
-- 'a href="/about"': About Us
-- 'img src="/logo.png" alt="Logo"':
-
-# Variables
-- h1: ${title}
-- p: ${site.description}
-
-# Conditionals
-- $if showBanner:
-    - div.banner: Hello!
-
-# Loops
-- $for item in items:
-    - li: ${item.name}
-
-# Partials
-- $partial: header
-- $partial: card
-  title: My Card
-  description: Card content
+assets:
+  loadUiFromCdn: true
+  loadConstructStyleSheetsPolyfill: true
 ```
 
-## Data Files
+Enable `codePreview` if you want fenced blocks like ```` ```html codePreview ```` to render a live preview panel.
+Use `showSource` to show/hide the source pane and `theme` to override the highlight theme for preview blocks.
+
+Set `build.keepMarkdownFiles: true` to keep source Markdown files in output in addition to generated HTML.
+Example mappings:
+- `pages/index.md` -> `_site/index.html` and `_site/index.md`
+- `pages/docs/intro.md` -> `_site/docs/intro/index.html` and `_site/docs/intro.md`
 
-`data/site.yaml` → available as `${site.name}`, `${site.nav}`, etc.
+`imports` lets you map aliases to remote YAML files (HTTP/HTTPS only). Use aliases in pages/templates:
+- page frontmatter: `template: base` or `template: docs`
+- template/page content: `$partial: docs/nav`
 
-## Collections
+Imported files are cached on disk under `.rettangoli/sites/imports/{templates|partials}/` (hashed filenames).
+Alias/url/hash mapping is tracked in `.rettangoli/sites/imports/index.yaml`.
+Build is cache-first: if a cached file exists, it is used without a network request.
 
-Tag pages to create collections:
+When an alias exists both remotely and locally, local files under `templates/` and `partials/` override the imported one.
+
+If you want to publish a manual `llms.txt`, place it in `static/llms.txt`; it will be copied to `_site/llms.txt`.
+
+## System Frontmatter
+
+Use `_bind` to map global data keys into page-local variables.
+
+Example:
 
 ```yaml
-# pages/blog/post.md
 ---
-tags: [blog]
+template: base
+_bind:
+  docs: feDocs
 ---
 ```
 
-```yaml
-# pages/blog.yaml
-- $for post in collections.blog:
-    - a href="${post.url}": ${post.data.title}
-```
+This resolves `docs` from `data/feDocs.yaml` for that page.
+`_bind` is a system property and is not exposed to templates directly.
 
-## Configuration
-
-`sites.config.js`:
-```javascript
-export default {
-  mdRender: customMarkdownRenderer,
-  functions: {
-    sortDate: (list) => list.sort((a, b) =>
-      new Date(b.data.date) - new Date(a.data.date)
-    )
-  }
-}
-```
+Rules:
+
+- `_bind` must be an object
+- each `_bind` value must be a non-empty string
+- each `_bind` value must point to an existing `data/*.yaml` key
+- `_bind` is removed from public frontmatter before rendering/collections
+
+Binding order:
+
+1. build page context from `deepMerge(globalData, frontmatterWithoutSystemKeys)`
+2. apply `_bind` aliases on top (alias wins for that key)
+
+## Pre-published Import Assets
+
+`@rettangoli/sites` publishes reusable template/partial YAML assets under `sites/` for URL imports.
 
-## Scripts
+- Base template: `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/templates/base.yaml`
+- Docs template: `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/templates/docs.yaml`
+- Generic partials: `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/{seo,navbar,mobile-nav,docs-sidebar}.yaml`
+- Legacy docs partial (compat, flat path): `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/docs-mobile-nav.yaml`
+
+See `sites/README.md` for full alias examples and required data contract.
+
+## Template Authoring Pattern
+
+Keep base templates as shells with minimal logic:
+
+- document root (`html`, `head`, `body`)
+- main content slot (`"${content}"`)
+- stable layout containers
+
+Put variant-specific behavior and data wiring in partials instead.
+Partials accept explicit parameters via `$partial`, so they are the preferred place for:
+
+- section-specific navigation data
+- conditional UI branches
+- reusable interactive blocks
+
+This keeps one template reusable across many page variants and avoids duplicated template files.
+
+## Commands
 
 ```bash
-bun run build       # Build site to _site/
-bun run watch       # Build + watch for changes
-bun run serve       # Serve _site/
-bun run screenshot  # Generate page screenshots
+bunx rtgl sites build
+bunx rtgl sites watch
+bunx rtgl sites build --quiet
+bunx rtgl sites watch --quiet
+bunx rtgl sites watch --reload-mode full
+bunx rtgl sites build --root-dir . --output-path dist
+bunx rtgl sites watch --root-dir . --output-path dist --reload-mode full
+```
+
+`--reload-mode body` (default) does fast body replacement; `--reload-mode full` forces full page refresh.
+`--root-dir`/`--output-path` are the preferred option names (`--rootDir`/`--outputPath` remain as legacy aliases).
+
+## Built-in Template Functions
+
+Available in YAML templates/pages without extra setup:
+
+- `encodeURI(value)`
+- `encodeURIComponent(value)`
+- `decodeURI(value)`
+- `decodeURIComponent(value)`
+- `jsonStringify(value, space = 0)`
+- `formatDate(value, format = "YYYYMMDDHHmmss", useUtc = true)`
+- `now(format = "YYYYMMDDHHmmss", useUtc = true)`
+- `sort(list, key, order = "asc")`
+- `md(content)`
+- `toQueryString(object)`
+
+`formatDate` tokens: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`.
+`decodeURI`/`decodeURIComponent` return the original input when decoding fails.
+`sort` supports `order` as `asc` or `desc` (default: `asc`), accepts dot-path keys (for example `data.date`), and returns a new array.
+`md` returns raw rendered HTML from Markdown for template insertion.
+
+## Screenshots
+
+`@rettangoli/sites` builds pages; screenshot capture is handled by `@rettangoli/vt`.
+
+Use VT against your generated site:
+
+1. Add `vt/specs/*.html` specs (use frontmatter `url` for the page to capture).
+2. Add `vt` config in `rettangoli.config.yaml`.
+3. Run `rtgl vt generate`, `rtgl vt report`, and `rtgl vt accept`.
+
+Example:
+
+```yaml
+vt:
+  path: ./vt
+  url: http://127.0.0.1:4173
+  service:
+    start: bun run preview
+  sections:
+    - title: pages
+      files: .
+```
+
+```html
+---
+title: home
+url: /
+---
+<div></div>
 ```
 
-## Templates
+`bun run preview` (or any equivalent local server command) must serve your built site on `vt.url` (for example serving `_site/` on port `4173`).
+
+## Full Architecture And Analysis
 
-Starter templates in `templates/`:
+See `docs/architecture-and-analysis.md` for:
 
-- **default** - Basic site with homepage, blog, and about page
+- End-to-end rendering flow
+- Data/context model used during render
+- URL/output mapping rules
+- Config contract details
+- Full robustness analysis and prioritized improvements

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rettangoli/sites",
-  "version": "0.2.7",
-  "description": "Generate static sites using Markdown and YAML. Straightforward, zero-complexity. Complete toolkit for landing pages, blogs, documentation, admin dashboards, and more.git remote add origin git@github.com:yuusoft-org/sitic.git",
+  "version": "1.0.0-rc10",
+  "description": "Generate static sites using Markdown and YAML for docs, blogs, and marketing sites.",
   "author": {
     "name": "Luciano Hanyon Wu",
     "email": "han4wluc@yuusoft.com"
@@ -14,15 +14,15 @@
   "files": [
     "src",
     "components",
-    "templates"
+    "templates",
+    "sites"
   ],
   "dependencies": {
+    "gray-matter": "^4.0.3",
     "jempl": "^0.3.1-rc1",
     "js-yaml": "^4.1.0",
     "markdown-it": "^14.1.0",
-    "minimatch": "^10.0.3",
-    "playwright": "^1.55.0",
-    "sharp": "^0.34.3",
+    "shiki": "^3.13.0",
     "ws": "^8.18.0",
     "yahtml": "0.0.4"
   },
@@ -50,7 +50,7 @@
     "dashboard"
   ],
   "bugs": {
-    "url": "https://github.com/yuusoft-org/sitic/issues"
+    "url": "https://github.com/yuusoft-org/rettangoli/issues"
   },
-  "homepage": "https://github.com/yuusoft-org/sitic#readme"
+  "homepage": "https://github.com/yuusoft-org/rettangoli/tree/main/packages/rettangoli-sites#readme"
 }

package/sites/README.md

@@ -0,0 +1,67 @@
+# Rettangoli Sites Import Assets
+
+This folder contains publish-only YAML templates/partials for `@rettangoli/sites` URL imports.
+These files are distribution assets, not `@rettangoli/sites` runtime source code.
+
+## Published Templates
+
+- Base shell template:
+  - `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/templates/base.yaml`
+- Docs layout template:
+  - `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/templates/docs.yaml`
+
+## Published Partials
+
+- `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/seo.yaml`
+- `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/navbar.yaml`
+- `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/mobile-nav.yaml`
+- `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/docs-sidebar.yaml`
+- `https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/docs-mobile-nav.yaml` (legacy compat partial, flat path)
+
+## Recommended Alias Map
+
+```yaml
+imports:
+  templates:
+    base: https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/templates/base.yaml
+    docs: https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/templates/docs.yaml
+  partials:
+    seo: https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/seo.yaml
+    navbar: https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/navbar.yaml
+    mobile-nav: https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/mobile-nav.yaml
+    docs-sidebar: https://cdn.jsdelivr.net/npm/@rettangoli/sites@<version>/sites/partials/docs-sidebar.yaml
+```
+
+## Frontmatter Examples
+
+Docs page:
+
+```yaml
+---
+template: docs
+_bind:
+  docs: docs
+title: Getting Started
+sidebarId: getting-started
+---
+```
+
+Regular page:
+
+```yaml
+---
+template: base
+title: Home
+---
+```
+
+## Docs Template Data Contract
+
+The `docs` template expects:
+
+- `docs.header` with `label` and `href`
+- `docs.items` (sidebar items)
+- `sidebarId`
+- `title`
+
+Use `_bind.docs` to map `docs` from a global data file (for example `data/docs.yaml`).

package/sites/partials/docs-mobile-nav.yaml

@@ -0,0 +1,7 @@
+- $if docsLayout && docsLayout.sidebar && docsLayout.sidebar.header && docsLayout.sidebar.items:
+    - 'rtgl-view hide md-show w=f d=v bgc=bg':
+        - 'rtgl-view pos=fix w=f h=56 bgc=bg av=c ph=lg bwb=xs z=10 style="top:0;left:0"':
+            - 'a href="${docsLayout.sidebar.header.href}" style="text-decoration:none;display:contents;color:inherit;"':
+                - rtgl-text s=md: ${docsLayout.sidebar.header.label}
+        - rtgl-view h=56:
+        - rtgl-sidebar selected-item-id=${sidebarId} header="${encodeURIComponent(jsonStringify(docsLayout.sidebar.header))}" items="${encodeURIComponent(jsonStringify(docsLayout.sidebar.items))}" w=f:

package/sites/partials/docs-sidebar.yaml

@@ -0,0 +1 @@
+- rtgl-sidebar selected-item-id=${sidebarId} header="${encodeURIComponent(jsonStringify(header))}" items="${encodeURIComponent(jsonStringify(items))}":

package/sites/partials/mobile-nav.yaml

@@ -0,0 +1,10 @@
+- 'rtgl-view data-mobile-autohide="true" hide md-show pos=fix w=f h=56 bgc=bg av=c ph=lg d=h bwb=xs z=10 style="top:0;left:0"':
+    - 'a href="${headerHref}" style="text-decoration:none;display:contents;color:inherit;"':
+        - rtgl-text s=md: ${headerLabel}
+    - rtgl-view w=1fg:
+    - 'rtgl-view id="mobile-menu-btn" data-testid="mobile-menu-btn" cur=pointer aria-label="Open docs navigation" aria-controls="mobile-nav-overlay" aria-expanded="false"':
+        - rtgl-svg id="mobile-menu-icon" data-testid="mobile-menu-icon" wh=24 svg=menu cur=pointer:
+
+- 'rtgl-view id="mobile-nav-overlay" pos=fix w=f bgc=bg z=20 d=v hidden style="top:56px;left:0;height:calc(100vh - 56px)"':
+    - rtgl-view sv w=f h=f:
+        - rtgl-sidebar selected-item-id=${sidebarId} header="${encodeURIComponent(jsonStringify(header))}" items="${encodeURIComponent(jsonStringify(items))}" w=f bwr=none hide-header="true":

package/sites/partials/navbar.yaml

@@ -0,0 +1,7 @@
+- 'rtgl-view data-mobile-autohide="true" bwb=xs w=f ah=c pos=fix bgc=bg':
+    - rtgl-view md-w="100vw" lg-w="768" w="1024" d=h av=c h=64 ph=lg:
+        - rtgl-text: ${title}
+        - rtgl-view w=1fg:
+        - rtgl-view d=h av=c:
+            - 'a href="https://github.com/yuusoft-org/rettangoli" target="_blank" style="text-decoration:none;display:contents;color:inherit;"':
+                - rtgl-svg.svg-icon wh="32" svg="github":

package/sites/partials/seo.yaml

@@ -0,0 +1,11 @@
+- meta charset="utf-8":
+- meta name="viewport" content="width=device-width,initial-scale=1":
+- title: "${title}"
+- meta name="description" content="${seo.description}":
+- link rel="canonical" href="${site.baseUrl}${page.url}":
+- link rel="icon" type="image/x-icon" href="/public/favicon.png":
+
+- meta property="og:title" content="${seo.title}":
+- meta property="og:description" content="${seo.description}":
+- meta property="og:site_name" content="${seo.ogSiteName}":
+- meta property="og:type" content="${seo.ogType}":

package/sites/templates/base.yaml

@@ -0,0 +1,25 @@
+- html lang="en":
+    - head:
+        - $partial: seo
+          page: ${page}
+          seo: ${seo}
+          title: ${title}
+        - link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc13/dist/themes/base.css":
+        - link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc13/dist/themes/theme-rtgl-slate.css":
+        - script src="https://cdn.jsdelivr.net/npm/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.min.js":
+        - script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc13/dist/rettangoli-iife-ui.min.js":
+        - script src="/public/rtgl-icons.js":
+
+    - body.dark:
+        - rtgl-view:
+            - rtgl-view pos="abs" edge="t" ah="c" bgc="bg":
+                - $partial: navbar
+                  title: ${site.navbar.title}
+                  cta: ${site.navbar.cta}
+            - rtgl-view w=f:
+                - rtgl-view h="48":
+                - rtgl-view w="f" ah="c":
+                    - rtgl-view w=f ph="lg" pb="lg" ah=c:
+                        - "${content}"
+
+        - script src="/public/mobile-nav.js":

package/sites/templates/docs.yaml

@@ -0,0 +1,37 @@
+- html lang="en":
+    - head:
+        - $partial: seo
+          page: ${page}
+          seo: ${seo}
+          title: ${title}
+        - link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc13/dist/themes/base.css":
+        - link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc13/dist/themes/theme-rtgl-slate.css":
+        - script src="https://cdn.jsdelivr.net/npm/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.min.js":
+        - script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc13/dist/rettangoli-iife-ui.min.js":
+        - script src="/public/rtgl-icons.js":
+
+    - body.dark:
+        - $partial: mobile-nav
+          headerLabel: ${docs.header.label}
+          headerHref: ${docs.header.href}
+          header: ${docs.header}
+          items: ${docs.items}
+          sidebarId: ${sidebarId}
+
+        - rtgl-view bgc="bg" w="f" d=h:
+            - 'rtgl-view md-hide pos=fix h=100vh bgc=bg style="left: 0"':
+                - $partial: docs-sidebar
+                  sidebarId: ${sidebarId}
+                  header: ${docs.header}
+                  items: ${docs.items}
+            - rtgl-view md-hide xl-show hide w=272:
+            - rtgl-view w="1fg" ah=c:
+                - rtgl-view pv="lg" lg-w="100vw" w="720" ph="lg" sv id="content-container":
+                    - rtgl-view hide md-show h=56:
+                    - rtgl-text s="h1" mb="lg": ${title}
+                    - "${content}"
+                    - rtgl-view h=200:
+            - 'rtgl-view xl-hide style="position: fixed; right: 0"':
+                - rtgl-page-outline id="page-outline" target-id="content-container" scroll-container-id="window" offset-top="80":
+
+        - script src="/public/mobile-nav.js":