Home · Docs · Configuration

Configuration

Every JamsEDU project has a configuration file that controls how the builder processes your site. This file is a standard JavaScript module that exports a single object containing your project's directory paths, optional settings, and build hooks. It tells the builder where your pages and assets live, where compiled HTML should be written, and where your templates are stored so every page can reuse shared markup like header.html and footer.html templates.

Which file is loaded

The builder looks for a configuration file in your project root, the directory you run jamsedu --watch or jamsedu --build from. It checks for .jamsedu/config.js first and falls back to jamsedu.config.js in the root if that does not exist. You only need one of these files.

The file uses standard ES module syntax: export default { ... } with properties separated by commas. There is no special syntax to learn beyond the option names documented below. To run a build with a different configuration file, use jamsedu --config path/to/file.js.

Required paths

Three directory paths are required in every configuration file. Each is relative to your project root. Use clean, stable names like www/private rather than relative prefixes like ./ or ../ to keep paths predictable during builds. 


        export default {
            destDir: 'output/',
            srcDir: 'src/',
            templateDir: 'src/templates'
        };

srcDir is your working directory where all authored content lives: .jhp pages, CSS, JavaScript, images, and other static assets. destDir is the build output where generated HTML and copied assets are written. This is what you upload or deploy to your hosting provider. You should never edit files inside destDir directly since it is regenerated on every build.

templateDir holds your shared HTML fragments and layout pieces that pages pull in using $include in JHP. Keeping templates in their own directory separates page content from site layout, so when you update something like header.html, every page that includes it picks up the change on the next build. Placing templateDir inside srcDir as shown above is the most common setup.

Options reference

The three directory paths listed below are required. All other options are optional. The pre and post options accept arrays of standard JavaScript functions using either traditional or arrow syntax. The builder calls these functions at the appropriate stage of the build pipeline.

destDir Required
Output directory where compiled HTML and copied assets are written for deployment or local preview.
srcDir Required
Input directory containing your pages, templates (if colocated), and all assets the build reads or copies from.
templateDir Required
Directory for shared HTML partials (include-only). JamsEdu passes it to JHP as the first includeSearchRoot (before srcDir) so $include('/…') can resolve here. Typically a templates folder inside srcDir.
websiteUrl Optional
Canonical absolute URL for your site (including https://), configured here in this exported object (.jamsedu/config.js). A full jamsedu --build (the default clean production pass) writes sitemap.xml under destDir when this property is set, so crawlers get full <loc> URLs. The same clean build pass always writes sitemap.json at the site root (next to published HTML); that file powers the masthead search and does not require websiteUrl. jamsedu --watch refreshes individual pages as you save but does not rewrite sitemap.json or sitemap.xml on every save; run jamsedu --build after substantive edits (or before deploy) so search and sitemap files match the full site.
verbose Optional
Set to true to enable detailed logging on every build without passing --verbose on the command line.
pre Optional
Array of functions that run before the main template pass. Each receives the build scope which includes a mutable DOM view of the page.
post Optional
Array of functions that run after templates have been merged but before the final HTML is written to disk. Merged with any built in post processing steps where applicable.
doNotCopy Optional
Additional deny-list extensions (without the leading dot) that should not be copied into destDir. This list is merged with JamsEdu's built-in safe defaults.
copyRules Optional
Advanced allow and deny copy rules. Supports allowExtensions, allowSuffixes, denyExtensions, and denySuffixes with deterministic precedence.
quarto Optional
Optional Quarto integration object: template (.qmd layout), assetsDir, and workingDir. If Quarto CLI is missing, JamsEDU writes a placeholder page per .qmd and continues building.
A Note on Extension Exclusions

doNotCopy adds to safe defaults rather than replacing them. If you need fine-grained control, use copyRules to explicitly allow or deny by extension or suffix.

Hooks

Hooks let you run your own JavaScript during the build to adjust HTML structure, inject repeated markup, or normalize content across pages. These are not browser scripts; the builder executes them while processing each page. pre hooks run before template expansion, and post hooks run after templates are applied but before the final HTML is written to disk.

Each hook receives structured access to the current document through a scope object, allowing you to query and modify the page tree. You do not need hooks for a straightforward static site. They are there for when templates and static assets alone are not enough.

For full details on the build pipeline, execution order, and working examples, see the Hooks page.