Feature reference · YASSB docs

58 features in yassb-web 2.0.0. This page is rendered from the feature catalogue that the build of YASSB checks, so it always matches the code.

Directives 8 Built-in renderers 2 Configuration 21 Command line 8 Translations 2 Content 2 Assets 4 Extension API 3 Behaviour 8

Directives

`directive.attributes`

stable since 1.0.0

Shared attribute syntax of directives: quoted values, JSON options, LANG and USERNAME placeholders.

<!-- create-from-data-source="LANG/news.json" renderer="list" options="{"order":["b","a"],"limit":3}" -->

Options: options: JSON (object or array) written as is inside double or single quotes, anywhere in the directive.
Rules: Values end at the closing quote; LANG anywhere in the directive (options included) becomes the current language; USERNAME becomes config.username (the text "undefined" if unset); invalid options JSON is reported and ignored.
Errors: OPTIONS_INVALID_JSON
Related: config.username directive.create-from-data-source

`directive.component`

stable since 1.0.0

Inserts an HTML, SVG or Markdown fragment from the components folder, recursively.

<!-- component="site/header.html" -->

Options: The value is a path relative to src/app/components (workingDir.components); LANG and USERNAME are replaced (see directive.attributes).
Rules: Each component is processed on its own (its directives run with fileFullPath = the component file) before being inserted into the including file; components can nest; .md/.txt components are converted from Markdown; front matter of a component becomes { key } placeholders of the page; a missing file leaves the comment in place (removed by the minifier); more than 40 levels of nesting is reported as a cycle; the regex accepts one directive per line.
Errors: COMPONENT_NOT_FOUND COMPONENT_UNSUPPORTED_FORMAT COMPONENT_CYCLE
Related: content.front-matter content.markdown directive.attributes

`directive.create-from-data-source`

stable since 1.0.0

Renders a JSON data source with a renderer and inserts the resulting HTML.

<!-- create-from-data-source="people/team.json" renderer="peopleCards" options="{"limit":3}" -->

Options: renderer: name in customRenderers or a built-in renderer (default basicElement); options: JSON passed to the renderer as props.options.
Rules: One JSON file per directive, path relative to src/app/data-sources (sub-folders allowed); the file is parsed again for every directive, so renderers may mutate their data; the renderer receives source (parsed JSON) and sourcePath; every occurrence of the same directive text in the file is replaced; a missing file or name leaves the comment (removed by the minifier) and is reported; invalid JSON or a throwing renderer fail the build.
Errors: DATA_SOURCE_MISSING_NAME DATA_SOURCE_NOT_FOUND DATA_SOURCE_INVALID_JSON
Related: api.custom-renderers directive.attributes renderer.basicElement

`directive.generate-from-files`

stable since 1.0.0

Generates one page per Markdown/text file from a template in pages-to-generate.

In src/app/pages-to-generate/blog/post.html: <h1>{ title }</h1> <!-- generate-from-files="blog" -->

Options: The value is a folder relative to src/app (workingDir.posts); USERNAME is replaced.
Rules: The directive must be in the template file itself, not in a component; .md and .txt files are read recursively; output is <out>/<template folder>/<file sub-folder>/<slug>.html with slug = front matter slug, else the title in kebab-case, else the file name; front matter placeholders are replaced at once and again in post-processing; generated pages then go through all directives; with i18n only templates inside a language folder (pages-to-generate/en/...) are translated, so a multi-language blog needs one template per language.
Errors: TEMPLATE_NO_DIRECTIVE TEMPLATE_SOURCE_NOT_FOUND MARKDOWN_EMPTY
Related: content.markdown content.front-matter

`directive.include-script-src`

stable since 1.0.0

Inserts the script tag of the bundled browser script.

<!-- include-script-src -->  →  <script src="/assets/js/main-1-0-0.min.js"></script>

Options: none
Rules: The text must be exactly ; the URL follows workingDir.scripts, workingDir.scriptsOutFolder and the version of package.json.
Related: assets.scripts assets.file-names

`directive.include-styles-src`

stable since 1.0.0

Inserts the stylesheet link of the compiled CSS.

<!-- include-styles-src -->  →  <link rel="stylesheet" href="/assets/css/styles-1-0-0.min.css">

Options: none
Rules: The text must be exactly ; the URL follows workingDir.styles, workingDir.stylesOutFolder and the version of package.json.
Related: assets.styles assets.file-names

`directive.public-file-list`

stable since 1.0.0

Lists the files of a folder of the output and renders them with a custom renderer.

<!-- public-file-list="assets/downloads" renderer="filesList" -->

Options: renderer (required, must be in customRenderers); options: JSON passed to the renderer.
Rules: The folder is relative to the output folder and scanned recursively in name order; source is [{ absolutePath, absoluteUrl }], sourcePath the scanned folder; only files already in the output are listed (assets are copied first).
Errors: PUBLIC_FILE_LIST_RENDERER_NOT_FOUND PUBLIC_FILE_LIST_NOT_FOUND
Related: api.custom-renderers assets.copy

`directive.url-to`

stable since 1.0.0

Replaced by the absolute URL of the output file whose path contains a fragment.

<a href="{{ url-to="about" }}">  <a href="{{ url-to="blog-post#comments" options="{"warning":false}" }}">

Options: #anchor is kept; options="{"warning":false}" silences the ambiguity warning.
Rules: The fragment is matched case-insensitively against every URL of the output (also as kebab-case and snake_case); with several matches the file closest to the current page wins, ties go to an index.html; with i18n only pages of languages already built are visible; the host (siteHost or the internal one) is stripped, so the result is root-relative (/en/about/index.html); no match inserts nothing and suggests the closest URL.
Errors: URL_TO_EMPTY URL_TO_NOT_FOUND URL_TO_AMBIGUOUS
Related: behaviour.sitemap config.siteHost

Built-in renderers

`renderer.basicElement`

stable since 1.0.0

Built-in renderer: one element per item, with item.description as content.

<ul><!-- create-from-data-source="items.json" renderer="basicElement" options="{"tag":"li","attributes":{"class":"x"}}" --></ul>

Options: tag (default span); attributes: object applied to every element (true → bare attribute, false → omitted, arrays joined with spaces).
Rules: source is an array of { description } or, with i18n, { description: { <lang>: text } }; descriptions are inserted as HTML; used as fallback when a directive has no or an unknown renderer.
Related: directive.create-from-data-source

`renderer.liDateDescription`

stable since 1.0.0

Built-in renderer: <li><u>date</u>: description</li> per item, with localized dates.

<ul><!-- create-from-data-source="timeline.json" renderer="liDateDescription" --></ul>

Options: none
Rules: date is { start, end } with YYYY, YYYY/MM or YYYY/MM/DD (formatted in the current language: "March 2020", "March 5, 2020"), end "-" means present (<span data-t="PRESENT">, translated by i18n), or { raw } inserted as is; description as in basicElement.
Related: renderer.basicElement i18n.translation

Configuration

`config.afterBuild`

stable since 2.0.0

Hook called after every build, for site validations.

afterBuild: (result) => { if (!result.ok) ... }

Options: function (BuildResult: ok, durationMs, diagnostics, out, watchMode) → void | Promise
Rules: Runs in build and watch (unlike npm postbuild); an exception fails the build.
Errors: HOOK_FAILED
Related: config.beforeBuild

`config.beforeBuild`

stable since 2.0.0

Hook called before every build.

beforeBuild: ({ watchMode, out, langs }) => { ... }

Options: function (BuildStartInfo) → void | Promise
Rules: Runs in build and watch after the config is loaded and the output cleaned; an exception stops the build.
Errors: HOOK_FAILED
Related: config.afterBuild

`config.cleanOut`

stable since 2.0.0

Empties the output folder before each build.

cleanOut: true  (or yassb build --clean)

Options: boolean, default false
Rules: Dot files at the root of the output (.git, .nojekyll) are kept; in watch mode only full rebuilds clean (a styles- or scripts-only rebuild keeps the pages); without it, deleted pages stay in the output.
Related: cli.build assets.copy

`config.customDirectives`

stable since 1.0.0

Registers custom directive classes.

customDirectives: [SiteLayoutDirective]

Options: array of classes, run in this order
Rules: Run after the built-in directives, for components and pages.
Related: api.custom-directives

`config.customRenderers`

stable since 1.0.0

Registers renderers by name.

customRenderers: { newsList, peopleCards }

Options: object name → function
Rules: A custom renderer with the name of a built-in one replaces it.
Related: api.custom-renderers

`config.devServerPort`

stable since 1.0.0

Port of the dev server.

devServerPort: 4000

Options: number, default 3000
Rules: --port overrides it; the next free port is used if busy.
Related: behaviour.dev-server

`config.esbuildOptions`

stable since 2.0.0

Extra esbuild options merged into the scripts build.

esbuildOptions: { target: 'es2020', external: ['jquery'] }

Options: esbuild build options
Rules: Merged over the defaults (entry, IIFE, target es2018, minify, define); overriding outfile/write changes where files go.
Related: assets.scripts

`config.files`

stable since 1.0.0

The configuration is read from config/ with the rules of the config npm package.

config/default.ts → export default { ... } as YassbConfig; config/production.ts merged when NODE_ENV=production.

Options: NODE_CONFIG_DIR (folder, several separated by :), NODE_CONFIG_ENV / NODE_ENV (deployment, default development), NODE_APP_INSTANCE, HOST/HOSTNAME, NODE_CONFIG (JSON merged last).
Rules: Files merged in order: default, {deployment}, {host}, {host}-{deployment}, local, local-{deployment}, each also as {name}-{instance}; extensions .js .cjs .ts .cts .mts .tsx .json; export default or module.exports; plain objects are merged deeply, arrays/functions/classes replaced; YAML/TOML/other formats are reported and skipped; a missing package imported by the config is explained (packages yassb-web 1.x used to install are named).
Errors: CONFIG_LOAD_FAILED CONFIG_MODULE_NOT_FOUND CONFIG_UNSUPPORTED_FILE
Related: api.define-config behaviour.site-code

`config.grayMatterOption`

stable since 1.0.0

Options of gray-matter for front matter.

grayMatterOption: { excerpt: true, excerpt_separator: '<!-- more -->' }

Options: gray-matter options
Rules: With excerpt, { excerpt } is available in generated pages.
Related: content.front-matter

`config.htmlMinificationOptions`

stable since 1.0.0

Options of html-minifier-terser for yassb build.

htmlMinificationOptions: { collapseWhitespace: true, removeComments: true, minifyCSS: true }

Options: html-minifier-terser options, default {} (almost no change)
Rules: Not applied in watch; a page the minifier cannot parse is written unminified and reported.
Errors: MINIFY_FAILED
Related: behaviour.post-processing

`config.i18n`

stable since 2.0.0

Options of the translation step.

i18n: { allowHtml: true }

Options: allowHtml: insert translations as HTML (default false)
Rules: Applies to data-t content, not to attributes.
Related: i18n.translation

`config.postProcessors`

stable since 1.0.0

Functions applied to the final HTML of every page.

postProcessors: [(html) => html.replace(...)]

Options: array of (html: string) => string
Rules: Run in order after translation and front matter, before minification, in build and watch, for every HTML file of the output; an exception or a non-string result fails the build.
Errors: POST_PROCESSOR_FAILED
Related: behaviour.post-processing

`config.showdownConverterOptions`

stable since 1.0.0

Options of the Showdown Markdown converter.

showdownConverterOptions: { tables: true, strikethrough: true }

Options: Showdown options, default { tables: true }
Rules: Replaces the default entirely (set tables again if needed).
Related: content.markdown

`config.siteHost`

stable since 1.0.0

Public host of the site.

siteHost: 'https://example.com'

Options: string URL
Rules: Keeps sitemap.xml in the output, with this host in its URLs; url-to strips the host so links stay root-relative (a host without trailing slash yields //path links, as in 1.x).
Related: behaviour.sitemap directive.url-to

`config.sitemap`

stable since 2.0.0

Disables sitemap.xml.

sitemap: false

Options: boolean, default true
Rules: url-to keeps working from memory; a sitemap written by a post processor is not deleted.
Related: behaviour.sitemap

`config.skipsStyles`

stable since 1.0.0

Disables the stylesheet step.

skipsStyles: true

Options: boolean, default false
Rules: No CSS file is written; include-styles-src still inserts its link.
Related: assets.styles

`config.strict`

stable since 2.0.0

Every reported error fails the build.

strict: true  (or --strict)

Options: boolean, default false
Rules: Without it only fatal problems exit 1; warnings never fail.
Related: behaviour.diagnostics

`config.stylesParser`

stable since 1.0.0

Replaces Sass with the site's own CSS pipeline (PostCSS, Tailwind…).

stylesParser: async (entry, entryAgain, outputPath) => css

Options: function (absolute entry, same entry, absolute output path) → string | Buffer | Promise
Rules: Must return the CSS without writing it; runs after the pages (so Tailwind sees generated HTML); in watch it reruns on every page rebuild; an exception fails the build.
Errors: STYLES_FAILED
Related: assets.styles

`config.username`

stable since 1.0.0

Replaces USERNAME in directive values.

username: 'alex' then <!-- generate-from-files="/home/USERNAME/notes" -->

Options: string
Rules: Replaced in every directive before its attributes are read; unset gives the text "undefined".
Related: directive.attributes

`config.webpackConfig`

legacy since 1.0.0

Legacy: bundles the scripts with the site's webpack configuration.

webpackConfig: { entry: ..., output: ..., module: { rules: [...] } }

Options: a complete webpack configuration
Rules: Requires webpack (and loaders) installed in the site; the configuration decides entry and output; prefer esbuildOptions.
Errors: SCRIPTS_FAILED
Related: assets.scripts

`config.workingDir`

stable since 1.0.0

Changes the folders of the project.

workingDir: { out: 'public', styles: 'styles/styles.css' }

Options: base, src, assets, i18n, app, pages, components, dataSources, pagesToGenerate, posts, scripts, styles, out, scriptsOutFolder, stylesOutFolder
Rules: base relative to the current folder; src and out to base; assets, i18n, app to src; the others to app; scriptsOutFolder and stylesOutFolder to out; missing folders and empty script/style entries are created.
Related: config.files

Command line

`cli.build`

stable since 1.0.0

yassb build: production build of the site.

yassb build [--strict] [--clean] [--out <dir>] [--json]

Options: --strict: exit 1 on any error; --clean: empty the output first (dot files kept); --out <dir>: build into another folder; --json: print { ok, durationMs, out, diagnostics } instead of logs.
Rules: Pages minified with htmlMinificationOptions, scripts minified; exit code 1 when site code throws, the config cannot load, a data source/stylesheet is invalid, or with --strict on any error; prints a summary with error/warning counts.
Related: behaviour.pipeline behaviour.diagnostics config.strict config.cleanOut

`cli.check`

stable since 2.0.0

yassb check: builds the site and validates it; exit code 1 on errors.

yassb check [--json] [--out <dir>] [--no-links]

Options: --json: report { ok, counts, diagnostics }; --out <dir>: build into another folder; --no-links (same as --links=false): skip the link check.
Rules: Builds in production mode (in the configured output unless --out), then adds: translation attributes left in pages, keys missing in some language file, keys never used, broken local href/src, components and data sources not used by any page, packages imported by site code but not declared in package.json; programmatic: checkProject().
Errors: I18N_UNTRANSLATED_ATTRIBUTE I18N_INCONSISTENT_KEYS I18N_UNUSED_KEY LINK_BROKEN UNUSED_COMPONENT UNUSED_DATA_SOURCE UNDECLARED_DEPENDENCY
Related: cli.inspect behaviour.diagnostics

`cli.docs`

stable since 2.0.0

yassb docs [topic]: prints the guide shipped with the package (docs/guide.md).

yassb docs   yassb docs renderers   yassb docs diagnostics   yassb docs --list   yassb docs features [id]

Options: --list: list topics; topic: a section of the guide (by slug or words of its title); features [id]: the feature catalogue, the checklist of what documentation must cover; --json: the catalogue as JSON.
Rules: Works offline in every project; the diagnostics topic also lists every diagnostic code.
Related: behaviour.diagnostics

`cli.help`

stable since 1.0.0

Command dispatch, help and version of the yassb command.

yassb help   yassb --help   yassb --version

Options: --help, -h: help; --version, -v: version.
Rules: Unknown commands print the help and exit 1; the command runs in the current folder, which is the project root.
Related: cli.build

`cli.inspect`

stable since 2.0.0

yassb inspect [query]: describes the project without building it.

yassb inspect   yassb inspect --json   yassb inspect news.json   yassb inspect HOME.TITLE

Options: --json: full manifest (pages, templates, components, dataSources, renderers, customDirectives, postProcessors, hooks, assets, i18n, diagnostics); query: file, data source, renderer, directive or i18n key.
Rules: Read-only: loads the configuration but runs no renderer and writes nothing; directives are listed with file:line, components transitively, LANG paths expanded for every language; problems visible statically (missing files, unknown renderers, invalid options) are listed; programmatic: inspectProject().
Related: cli.check behaviour.diagnostics

`cli.new`

stable since 1.0.0

yassb new <name>: creates a project from the starter.

yassb new my-site

Options: name (required): converted to kebab-case for the folder and package name.
Rules: Refuses a non-empty existing folder; the starter has config/default.ts, a renderer in builder/, a data source, components, Sass and TypeScript entries, AGENTS.md and CLAUDE.md for coding agents, and yassb-web as devDependency.
Related: config.files

`cli.serve`

stable since 1.0.0

yassb serve: serves the output folder without building.

yassb serve [--port <n>]

Options: --port <n>: port (default devServerPort or 3000).
Rules: Uses the same routing as watch, without live reload; loads the configuration only to find the output folder and languages.
Related: behaviour.dev-server

`cli.watch`

stable since 1.0.0

yassb watch: build, serve with live reload, rebuild on every change.

yassb watch [--port <n>] [--clean] [--strict]

Options: --port <n>: dev server port (default devServerPort or 3000; 0 = any free port); --clean: empty the output before the first build; --strict: passed to every build.
Rules: The whole project is watched except the output folder, node_modules, .git and editor temp files; every build runs in a fresh child process, so config, renderers, directives, package.json and tsconfig changes are always picked up; a stylesheet change only recompiles styles (CSS swapped without reload), a change to a file used only by the scripts only rebundles them, other changes rebuild pages (and styles with a custom stylesParser), changes outside src or to site code rebuild everything; errors are printed and shown in the browser overlay while the server keeps running; changes during a build are queued into one more build; pages are not minified.
Errors: BUILD_CRASHED
Related: behaviour.dev-server behaviour.live-reload behaviour.site-code

Translations

`i18n.languages`

stable since 1.0.0

The languages of the site are the names of the JSON files in src/i18n.

src/i18n/en.json, src/i18n/it.json → every page built into <out>/en/ and <out>/it/

Options: workingDir.i18n changes the folder.
Rules: Languages are sorted by name and processed in that order; the first one is served at / by the dev server; without the folder (or JSON files) the site is single-language and pages go to <out>/.
Related: i18n.translation behaviour.dev-server

`i18n.translation`

stable since 1.0.0

Translates marked text and attributes of every page into each language.

<h1 data-t="HOME.TITLE">Welcome</h1>  <p data-t>Welcome</p>  <img data-attr-t alt-t="HOME.LOGO">  <p data-t="GREET" data-t-interpolate>

Options: config.i18n.allowHtml inserts translations as HTML; data-t-interpolate / data-attr-t-interpolate replace {{KEY}} placeholders.
Rules: Runs after all directives, so renderer output is translated; data-t with no value uses the element text as key; any <attr>-t on an element with data-attr-t sets <attr>; keys are flat ("HOME.TITLE") or nested objects; a missing key keeps the original text; translation attributes are removed; only translated elements are rewritten, the rest of the page is kept byte for byte; translations are escaped as text unless allowHtml; pages outside language folders are not translated.
Errors: I18N_MISSING_KEY I18N_INVALID_FILE I18N_UNCLOSED_ELEMENT
Related: i18n.languages config.i18n

Content

`content.front-matter`

stable since 1.0.0

{ key } placeholders are replaced with front matter values.

---\ntitle: Hello\ndate: 2024-01-15\n---  then <title>{ title }</title>

Options: none
Rules: One space inside each brace; values come from Markdown files, components with front matter and the data returned by custom directives; strings inserted as they are (not escaped), dates and the date key as ISO strings, other values as JSON; replaced after components and again in post-processing.
Errors: FRONT_MATTER_INVALID_DATE
Related: content.markdown api.custom-directives

`content.markdown`

stable since 1.0.0

Markdown/text files are converted to HTML (Showdown) with YAML front matter (gray-matter).

<!-- component="intro.md" -->, or the files of a generate-from-files folder.

Options: config.showdownConverterOptions (default { tables: true }); config.grayMatterOption (e.g. excerpt).
Rules: Front matter becomes { key } placeholders; excerpt and language found by gray-matter are added to the front matter; empty files are reported.
Errors: MARKDOWN_EMPTY
Related: content.front-matter directive.generate-from-files

Assets

`assets.copy`

stable since 1.0.0

src/assets is copied as it is to the output.

src/assets/img/logo.png → <out>/assets/img/logo.png

Options: workingDir.assets changes the folder.
Rules: Copied first, before pages; files with unchanged size and modification time are skipped; files deleted from src stay in the output unless cleanOut.
Related: config.cleanOut

`assets.file-names`

stable since 1.0.0

Output scripts and styles are named after their entry and the site version.

scripts/main.ts at version 1.2.0 → main-1-2-0.min.js; styles/styles.scss → styles-1-2-0.min.css

Options: none (version from the site's package.json)
Rules: Dots of the version become dashes; changing the version changes the URLs inserted by include-script-src / include-styles-src.
Related: directive.include-script-src directive.include-styles-src

`assets.scripts`

stable since 1.0.0

The browser script entry is bundled with esbuild.

src/app/scripts/main.ts (imports, npm packages, TS/JSX) → <out>/assets/js/main-<version>.min.js

Options: config.esbuildOptions (merged), config.webpackConfig (legacy, webpack from the site), workingDir.scripts / scriptsOutFolder.
Rules: IIFE for the browser, target es2018, minified in build, inline source map in watch, process.env.NODE_ENV = "production", JSX settings from tsconfig.json; bundled in parallel and written at the end of the build; an empty entry is created if missing.
Errors: SCRIPTS_FAILED
Related: directive.include-script-src assets.file-names

`assets.styles`

stable since 1.0.0

The stylesheet entry is compiled with Sass, or with the site's stylesParser.

src/app/styles/styles.scss → <out>/assets/css/styles-<version>.min.css

Options: config.stylesParser, config.skipsStyles, workingDir.styles / stylesOutFolder.
Rules: Sass output is compressed, imports resolved from the file and from the project root; compiled after the pages; a Sass error or a throwing stylesParser fails the build; an empty entry is created if missing.
Errors: STYLES_FAILED
Related: directive.include-styles-src config.stylesParser assets.file-names

Extension API

`api.custom-directives`

stable since 1.0.0

Site-defined directives: classes with a static regex whose init() rewrites the HTML.

class YearDirective implements YassbDirective { static regex = /<!--\s*current-year\s*-->/g; constructor(private args: YassbDirectiveProps) {} init() { return { html: ..., data: {} }; } }  then customDirectives: [YearDirective]

Options: none (registered with config.customDirectives)
Rules: Built-in directives run first, then custom ones in the order of customDirectives; init() is called once per regex match with the HTML updated by the previous call, so directives must be idempotent; components are processed before the page that includes them (fileFullPath is the component in src, then the page in out); data values become { key } placeholders; YassbBaseDirective copies the props to protected fields; an exception or a missing html fails the build with the directive location.
Errors: DIRECTIVE_NO_REGEX DIRECTIVE_FAILED
Related: config.customDirectives directive.component

`api.custom-renderers`

stable since 1.0.0

Site-defined functions that turn data into HTML for create-from-data-source and public-file-list.

export function newsList({ source, options, lang }: RendererProps<News[], { limit?: number }>): string { ... }  then customRenderers: { newsList }

Options: Props: source, sourcePath, options, lang, currentFilePath, config, frontMatterStore.
Rules: A renderer returns a string and must not write files; without renderer attribute basicElement is used (warning), with an unknown name basicElement is used (error); a throwing renderer fails the build with the directive location and inserts nothing; emitted <span data-t="KEY"> is translated afterwards.
Errors: RENDERER_MISSING RENDERER_NOT_FOUND RENDERER_FAILED
Related: config.customRenderers directive.create-from-data-source i18n.translation

`api.define-config`

stable since 2.0.0

Identity helper that types a configuration file.

import { defineConfig } from 'yassb-web'; export default defineConfig({ siteHost: 'https://example.com' });

Options: none
Rules: Equivalent to `export default {...} as YassbConfig`; requires yassb-web installed in the site because it is a runtime import.
Related: config.files

Behaviour

`behaviour.dev-server`

stable since 1.0.0

Development server of watch and serve (not for production).

http://localhost:3000/  →  <out>/<first language>/index.html

Options: config.devServerPort, --port.
Rules: /<lang>/... → <out>/<lang>/...; other paths → <out>/<first language>/..., then <out>/...; folders redirect to a trailing slash and serve index.html; not found → the home page with status 200; Range requests supported; if the port is busy the next ones are tried.
Related: cli.watch cli.serve i18n.languages

`behaviour.diagnostics`

stable since 2.0.0

Every problem is reported with a stable code, file, line and hint.

error DATA_SOURCE_NOT_FOUND src/app/pages/index.html:12 …  /  yassb build --json  /  yassb docs diagnostics

Options: --json on build and check; config.strict.
Rules: Pages are reported on their source file (pages/, the template, or the Markdown file); the same problem reported for a component and its page is kept once; fatal problems (exceptions in site code, invalid JSON, config errors) exit 1, others only with strict; missing translations are collected and summarised.
Related: cli.check config.strict

`behaviour.live-reload`

stable since 2.0.0

In watch mode pages reload by themselves and show build errors.

automatic in yassb watch (script injected before </body>, events on /__yassb/events)

Options: none
Rules: Reload after a page or script rebuild; CSS swapped without reload after a styles-only rebuild; a badge while rebuilding; an overlay lists the errors of the last build (code, file:line, message, hint), hidden when fixed; status also at /__yassb/status; reloads when the watch process restarts.
Related: cli.watch behaviour.diagnostics

`behaviour.output-lock`

stable since 2.0.0

Only one YASSB process at a time writes an output folder; a second one stops with a clear message.

Running `yassb build` while `yassb watch` serves the same folder → error OUTPUT_LOCKED naming the other process.

Options: none (use --out <dir> to build somewhere else)
Rules: build and check hold the lock during the build; watch holds it for its whole session and its rebuilds share it; the lock file is in the system temporary folder (never in the output); a lock left by a process that no longer exists (crash, kill -9) is taken over (the message names the lock file to delete if its process id was reused); different output folders never conflict; the second process exits with code 1 without writing anything.
Errors: OUTPUT_LOCKED
Related: cli.build cli.watch cli.check

`behaviour.pipeline`

stable since 1.0.0

The fixed order in which a build processes a site.

yassb build, yassb watch, or programmatically: await runBuild({ strict: true }) in the project folder.

Options: BuildOptions: watchMode, steps { html, styles, scripts }, strict, clean, outDir.
Rules: config → beforeBuild → assets copy → scripts bundling starts → generate-from-files → for each language: copy pages (all files of pages/), list output files (url-to, sitemap), then per HTML page: components → front matter → built-in directives → custom directives → translation → post-processing of every HTML file of the output → styles → scripts written → afterBuild; directives left in a page after processing are reported.
Errors: DIRECTIVE_UNPROCESSED
Related: behaviour.post-processing api.custom-directives i18n.translation

`behaviour.post-processing`

stable since 1.0.0

Last step for every HTML file of the output.

automatic; customize with config.postProcessors and config.htmlMinificationOptions

Options: none
Rules: For every .html/.htm in the output (assets included): { key } placeholders → postProcessors in order → minification in build, or in watch the live-reload script before </body> and removal of the Content-Security-Policy meta; runs after translation.
Related: config.postProcessors config.htmlMinificationOptions behaviour.live-reload

`behaviour.site-code`

stable since 1.0.0

Configuration and site code can be TypeScript, TSX or JavaScript.

config/default.ts importing builder/renderers.tsx

Options: The site's tsconfig.json (jsx, decorators, class fields).
Rules: Under Node each file is compiled on its own to CommonJS with esbuild (like ts-node --transpile-only): __dirname, relative imports and require work as in Node; no type checking; stack traces point to the TS lines; Bun runs TypeScript natively; a syntax error is reported with file and line.
Errors: CONFIG_LOAD_FAILED
Related: config.files

`behaviour.sitemap`

stable since 1.0.0

sitemap.xml lists every file of the output; it is also the list url-to searches.

<out>/sitemap.xml with <loc>https://example.com/en/index.html</loc> entries

Options: config.siteHost (keeps the file and is the host of the URLs), config.sitemap: false (never written).
Rules: Regenerated before each language is processed; includes assets and every file; without siteHost the host is http://fake.host/ and the file is deleted at the end of the build (after post-processing); post processors may replace it.
Related: directive.url-to config.siteHost config.sitemap