@rettangoli/sites 0.2.7 → 1.0.0-rc2

package/README.md

@@ -1,133 +1,164 @@
 # 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
 ```
 
-## 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.
 
-`data/site.yaml` → available as `${site.name}`, `${site.nav}`, etc.
+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`
 
-## Collections
+If you want to publish a manual `llms.txt`, place it in `static/llms.txt`; it will be copied to `_site/llms.txt`.
 
-Tag pages to create collections:
+## Commands
 
-```yaml
-# pages/blog/post.md
----
-tags: [blog]
----
+```bash
+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)`
+- `toQueryString(object)`
+
+`formatDate` tokens: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`.
+`decodeURI`/`decodeURIComponent` return the original input when decoding fails.
+
+## 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
-# pages/blog.yaml
-- $for post in collections.blog:
-    - a href="${post.url}": ${post.data.title}
+vt:
+  path: ./vt
+  url: http://127.0.0.1:4173
+  service:
+    start: bun run preview
+  sections:
+    - title: pages
+      files: .
 ```
 
-## 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)
-    )
-  }
-}
+```html
+---
+title: home
+url: /
+---
+<div></div>
 ```
 
-## Scripts
-
-```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
-```
+`bun run preview` (or any equivalent local server command) must serve your built site on `vt.url` (for example serving `_site/` on port `4173`).
 
-## Templates
+## 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-rc2",
+  "description": "Generate static sites using Markdown and YAML for docs, blogs, and marketing sites.",
   "author": {
     "name": "Luciano Hanyon Wu",
     "email": "han4wluc@yuusoft.com"
@@ -17,12 +17,11 @@
     "templates"
   ],
   "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 +49,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/src/builtinTemplateFunctions.js

@@ -0,0 +1,85 @@
+function toDate(value) {
+  if (value instanceof Date) {
+    return value;
+  }
+
+  if (value === undefined || value === null || value === '') {
+    return new Date();
+  }
+
+  return new Date(value);
+}
+
+function pad2(value) {
+  return String(value).padStart(2, '0');
+}
+
+function formatDateImpl(value, format = 'YYYYMMDDHHmmss', useUtc = true) {
+  const date = toDate(value);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+
+  const read = (localGetter, utcGetter) => (useUtc ? utcGetter.call(date) : localGetter.call(date));
+  const tokens = {
+    YYYY: String(read(date.getFullYear, date.getUTCFullYear)),
+    MM: pad2(read(date.getMonth, date.getUTCMonth) + 1),
+    DD: pad2(read(date.getDate, date.getUTCDate)),
+    HH: pad2(read(date.getHours, date.getUTCHours)),
+    mm: pad2(read(date.getMinutes, date.getUTCMinutes)),
+    ss: pad2(read(date.getSeconds, date.getUTCSeconds)),
+  };
+
+  return String(format).replace(/YYYY|MM|DD|HH|mm|ss/g, (token) => tokens[token]);
+}
+
+function jsonStringify(value, space = 0) {
+  const indent = Number.isFinite(Number(space))
+    ? Math.max(0, Math.min(10, Math.trunc(Number(space))))
+    : 0;
+  const result = JSON.stringify(value, null, indent);
+  return result === undefined ? '' : result;
+}
+
+function toQueryString(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return '';
+  }
+
+  const params = new URLSearchParams();
+  for (const [key, raw] of Object.entries(value)) {
+    if (raw === undefined || raw === null) {
+      continue;
+    }
+    if (Array.isArray(raw)) {
+      for (const item of raw) {
+        params.append(key, String(item));
+      }
+      continue;
+    }
+    params.set(key, String(raw));
+  }
+  return params.toString();
+}
+
+function safeDecode(value, decoder) {
+  const input = String(value ?? '');
+  try {
+    return decoder(input);
+  } catch {
+    return input;
+  }
+}
+
+export const builtinTemplateFunctions = {
+  encodeURI: (value) => encodeURI(String(value ?? '')),
+  encodeURIComponent: (value) => encodeURIComponent(String(value ?? '')),
+  decodeURI: (value) => safeDecode(value, decodeURI),
+  decodeURIComponent: (value) => safeDecode(value, decodeURIComponent),
+  jsonStringify,
+  formatDate: formatDateImpl,
+  now: (format = 'YYYYMMDDHHmmss', useUtc = true) => formatDateImpl(new Date(), format, useUtc),
+  toQueryString,
+};
+
+export default builtinTemplateFunctions;

package/src/cli/build.js

@@ -6,24 +6,31 @@ import { loadSiteConfig } from '../utils/loadSiteConfig.js';
  * Build the static site
  * @param {Object} options - Options for building the site
  * @param {string} options.rootDir - Root directory of the site (defaults to cwd)
+ * @param {string} options.outputPath - Output directory path (relative to rootDir by default)
  * @param {Object} options.md - Optional markdown renderer
  * @param {boolean} options.quiet - Suppress build output logs
- * @param {boolean} options.isScreenshotMode - Whether building for screenshot capture
+ * @param {boolean} options.isScreenshotMode - Optional build flag exposed to templates via build.isScreenshotMode
  */
 export const buildSite = async (options = {}) => {
-  const { rootDir = process.cwd(), md, functions, quiet = false, isScreenshotMode = false } = options;
+  const {
+    rootDir = process.cwd(),
+    outputPath = '_site',
+    md,
+    functions,
+    quiet = false,
+    isScreenshotMode = false
+  } = options;
 
-  // Load config file if needed
-  let config = {};
-  if (!md || !functions) {
-    config = await loadSiteConfig(rootDir);
-  }
+  const config = await loadSiteConfig(rootDir);
 
   const build = createSiteBuilder({
     fs,
     rootDir,
-    md: md || config.mdRender,
-    functions: functions || config.functions || {},
+    outputPath,
+    md,
+    markdown: config.markdown || {},
+    keepMarkdownFiles: config.build?.keepMarkdownFiles === true,
+    functions: functions || {},
     quiet,
     isScreenshotMode
   });

package/src/cli/init.js

@@ -11,9 +11,9 @@ export function initSite({ projectName, template = 'default' }) {
 
   // Check if template exists
   if (!existsSync(templatePath)) {
-    const available = readdirSync(templatesDir).filter(f =>
-      existsSync(resolve(templatesDir, f, 'package.json'))
-    );
+    const available = readdirSync(templatesDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name);
     console.error(`Template "${template}" not found.`);
     console.error(`Available templates: ${available.join(', ')}`);
     process.exit(1);
@@ -33,6 +33,6 @@ export function initSite({ projectName, template = 'default' }) {
   console.log('');
   console.log('Next steps:');
   console.log(`  cd ${projectName}`);
-  console.log('  bun install');
-  console.log('  bun run build');
+  console.log('  bunx rtgl sites build');
+  console.log('  bunx rtgl sites watch');
 }