Assets and configuration
Options
Every option is optional. Types come with the package: YassbConfig, or defineConfig().
| Option | Default | Meaning |
|---|---|---|
workingDir | see Project structure | folder names |
customRenderers | {} | renderers by name; a name of a built-in replaces it |
customDirectives | [] | custom directive classes, run in this order |
postProcessors | [] | (html) => html applied to every page at the end (pipeline) |
htmlMinificationOptions | {} | html-minifier-terser options for build |
stylesParser | Sass | your own CSS compiler (styles) |
skipsStyles | false | no stylesheet |
esbuildOptions | — | extra esbuild options for the scripts |
webpackConfig | — | legacy: bundle scripts with the site's webpack |
showdownConverterOptions | { tables: true } | Markdown options |
grayMatterOption | — | front matter options (excerpts) |
siteHost | — | public host; keeps sitemap.xml (end it with /) |
sitemap | true | false never writes sitemap.xml |
cleanOut | false | empty the output before building (dot files such as .git are kept) |
relativeUrls | false | links and asset URLs relative to each page, so the site works from a sub-folder |
strict | false | any reported error fails the build |
i18n.allowHtml | false | insert translations as HTML |
devServerPort | 3000 | port of watch and serve |
username | — | replaces USERNAME in directives |
beforeBuild | — | hook before every build, in build and watch |
afterBuild | — | hook after every build, with { ok, diagnostics, out, durationMs, watchMode } |
cleanOut
Without it, files you delete from the sources stay in the output. With cleanOut: true (or yassb build --clean) the output folder is emptied first, keeping dot files at its root, so a deployment repository in the output folder survives. In watch mode only full rebuilds clean; a styles-only rebuild keeps the pages.
relativeUrls
Links such as /assets/css/styles.css or /about/ only work when the site is served from the root of a host. A GitHub Pages project site lives under https://<user>.github.io/<repository>/: set relativeUrls: true (the github-pages preset of yassb new does it) and every URL that starts with a single / is written relative to its page. On en/about.html, /assets/css/styles.css becomes ../assets/css/styles.css. The same output works at the root, in any sub-folder and in watch.
YASSB rewrites URL attributes (href, src, action, poster, srcset…), inline style, <style> blocks, the markup inside <noscript>, and url() and @import in the compiled stylesheet, after your postProcessors. It leaves alone URLs with a host or a scheme, pages with a <base href>, URLs built in JavaScript, files copied from src/assets and sitemap.xml. A 404.html that the host serves at any depth cannot resolve relative URLs: keep it self-contained.
strict
By default only problems that make the build unusable exit with code 1: exceptions in your code, invalid JSON, a configuration that does not load, a broken stylesheet. Everything else is printed with file and line. With strict: true (or --strict) every error fails the build. Warnings never do.