kempo-server 3.0.2 → 3.0.4

package/docs-src/templating.page.html

@@ -8,8 +8,14 @@
 				<li><a href="#overview">Overview</a></li>
 				<li><a href="#file-types">File Types</a></li>
 				<li><a href="#templates">Templates</a></li>
-				<li><a href="#pages">Pages</a></li>
+				<li><a href="#pages">Pages</a>
+					<ul>
+						<li><a href="#frontmatter">Frontmatter</a></li>
+					</ul>
+				</li>
 				<li><a href="#fragments">Fragments</a></li>
+				<li><a href="#global-files">Global Files</a></li>
+				<li><a href="#fragments-vs-globals">Fragments vs. Global Files</a></li>
 				<li><a href="#variables">Variables</a></li>
 				<li><a href="#conditionals">Conditionals</a></li>
 				<li><a href="#loops">Loops</a></li>
@@ -20,22 +26,23 @@
 		</nav>
 
 		<h2 id="overview">Overview</h2>
-		<p>The templating system uses three file types that work together:</p>
+		<p>The templating system uses four file types that work together:</p>
 		<ul>
 			<li><strong>Templates</strong> (<code>*.template.html</code>) &mdash; Shared page layouts with named content slots</li>
 			<li><strong>Pages</strong> (<code>*.page.html</code>) &mdash; Individual pages that fill template slots with content</li>
 			<li><strong>Fragments</strong> (<code>*.fragment.html</code>) &mdash; Reusable HTML partials included in templates or other fragments</li>
+			<li><strong>Globals</strong> (<code>*.global.html</code>) &mdash; Site-wide content blocks automatically injected into every page render</li>
 		</ul>
 		<p>All three file types are blocked from being served directly by the default <code>disallowedRegex</code> configuration.</p>
 
 		<h2 id="file-types">File Types</h2>
 		<p>A typical project structure:</p>
-		<pre><code class="hljs markdown">my-site/<br />├─ default.template.html    # Shared layout<br />├─ nav.fragment.html        # Reusable navigation<br />├─ footer.fragment.html     # Reusable footer<br />├─ index.page.html          # Homepage → renders to index.html<br />├─ about.page.html          # About → renders to about.html<br />├─ blog/<br />│  ├─ index.page.html       # Blog index → blog/index.html<br />│  ├─ post-1.page.html      # Blog post → blog/post-1.html<br /></code></pre>
+		<pre><code class="hljs markdown">my-site/<br />├─ default.template.html    # Shared layout<br />├─ nav.fragment.html        # Reusable navigation<br />├─ footer.fragment.html     # Reusable footer<br />├─ analytics.global.html    # Site-wide scripts injected into every page<br />├─ index.page.html          # Homepage → renders to index.html<br />├─ about.page.html          # About → renders to about.html<br />├─ blog/<br />│  ├─ index.page.html       # Blog index → blog/index.html<br />│  ├─ post-1.page.html      # Blog post → blog/post-1.html<br /></code></pre>
 		<p>Templates and fragments are resolved by walking up the directory tree from the page file to the root, so subdirectories can override them by providing their own versions.</p>
 
 		<h2 id="templates">Templates</h2>
 		<p>A template defines the shared HTML structure for your pages. Use <code>&lt;location&gt;</code> tags to define named content slots that pages will fill.</p>
-		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- default.template.html --&gt;</span><br /><span class="hljs-meta">&lt;!DOCTYPE html&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en"</span>&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">head</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">meta</span> <span class="hljs-attr">charset</span>=<span class="hljs-string">"UTF-8"</span> /&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">title</span>&gt;</span>{{title}}<span class="hljs-tag">&lt;/<span class="hljs-name">title</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">head</span>&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">body</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">fragment</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"nav"</span> /&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">main</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">h1</span>&gt;</span>{{pageName}}<span class="hljs-tag">&lt;/<span class="hljs-name">h1</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">location</span> /&gt;</span><br />  <span class="hljs-tag">&lt;/<span class="hljs-name">main</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">location</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"scripts"</span>&gt;</span><br />    <span class="hljs-comment">&lt;!-- default scripts if page doesn't provide any --&gt;</span><br />  <span class="hljs-tag">&lt;/<span class="hljs-name">location</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">body</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">html</span>&gt;</span></code></pre>
+		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- default.template.html --&gt;</span><br /><span class="hljs-meta">&lt;!DOCTYPE html&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en"</span>&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">head</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">meta</span> <span class="hljs-attr">charset</span>=<span class="hljs-string">"UTF-8"</span> /&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">title</span>&gt;</span>&#123;&#123;title&#125;&#125;<span class="hljs-tag">&lt;/<span class="hljs-name">title</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">head</span>&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">body</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">fragment</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"nav"</span> /&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">main</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">h1</span>&gt;</span>&#123;&#123;pageName&#125;&#125;<span class="hljs-tag">&lt;/<span class="hljs-name">h1</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">location</span> /&gt;</span><br />  <span class="hljs-tag">&lt;/<span class="hljs-name">main</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">location</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"scripts"</span>&gt;</span><br />    <span class="hljs-comment">&lt;!-- default scripts if page doesn't provide any --&gt;</span><br />  <span class="hljs-tag">&lt;/<span class="hljs-name">location</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">body</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">html</span>&gt;</span></code></pre>
 
 		<h3>Location Tags</h3>
 		<p>Locations are named slots in a template that pages fill with content. The <code>name</code> attribute is optional &mdash; a <code>&lt;location&gt;</code> without a name defaults to <code>"default"</code>.</p>
@@ -46,15 +53,22 @@
 		</ul>
 
 		<h2 id="pages">Pages</h2>
-		<p>A page file wraps its content in a <code>&lt;page&gt;</code> root element and uses <code>&lt;content&gt;</code> blocks to fill the template's locations. The <code>location</code> attribute is optional &mdash; a <code>&lt;content&gt;</code> block without one targets the <code>"default"</code> location. Multiple <code>&lt;content&gt;</code> blocks targeting the same location are concatenated in order.</p>
+		<p>A page file wraps its content in a <code>&lt;page&gt;</code> root element and uses <code>&lt;content&gt;</code> blocks to fill the template's locations. The <code>location</code> attribute is optional &mdash; a <code>&lt;content&gt;</code> block without one targets the <code>"default"</code> location. Multiple <code>&lt;content&gt;</code> blocks targeting the same location are merged and sorted by <code>priority</code> (higher first, default <code>0</code>).</p>
 		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- about.page.html → renders to about.html --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">page</span> <span class="hljs-attr">pageName</span>=<span class="hljs-string">"About Us"</span> <span class="hljs-attr">title</span>=<span class="hljs-string">"About - My Site"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">content</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">p</span>&gt;</span>Welcome to our about page.<span class="hljs-tag">&lt;/<span class="hljs-name">p</span>&gt;</span><br />  <span class="hljs-tag">&lt;/<span class="hljs-name">content</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">page</span>&gt;</span></code></pre>
 
 		<h3>Page Attributes</h3>
-		<p>Attributes on the <code>&lt;page&gt;</code> tag become template variables. In the example above, <code>{{pageName}}</code> resolves to <code>About Us</code> and <code>{{title}}</code> resolves to <code>About - My Site</code>.</p>
+		<p>Attributes on the <code>&lt;page&gt;</code> tag become template variables. In the example above, <code>&#123;&#123;pageName&#125;&#125;</code> resolves to <code>About Us</code> and <code>&#123;&#123;title&#125;&#125;</code> resolves to <code>About - My Site</code>.</p>
 		<p>The special <code>template</code> attribute selects which template to use. It defaults to <code>default</code>, which looks for <code>default.template.html</code>.</p>
 		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- Uses blog.template.html instead of default.template.html --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">page</span> <span class="hljs-attr">template</span>=<span class="hljs-string">"blog"</span> <span class="hljs-attr">title</span>=<span class="hljs-string">"My Post"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">content</span> <span class="hljs-attr">location</span>=<span class="hljs-string">"main"</span>&gt;</span>...<span class="hljs-tag">&lt;/<span class="hljs-name">content</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">page</span>&gt;</span></code></pre>
 
-		<h2 id="fragments">Fragments</h2>
+		<h3 id="frontmatter">Frontmatter</h3>
+		<p>Any content before the opening <code>&lt;page&gt;</code> tag is ignored by the renderer. This makes it a natural place for author metadata, description, dates, or any notes that belong with the file but shouldn't appear in the output &mdash; similar to frontmatter in other static site generators.</p>
+		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!--
+  author: Dustin Poissant
+  date: 2026-04-10
+  description: Overview of the routing system
+--&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">page</span> <span class="hljs-attr">title</span>=<span class="hljs-string">"Routing"</span>&gt;</span><br />  ...<br /><span class="hljs-tag">&lt;/<span class="hljs-name">page</span>&gt;</span></code></pre>
+		<p>The comment is purely for the author &mdash; nothing before <code>&lt;page&gt;</code> is parsed or rendered.</p>
 		<p>Fragments are reusable HTML partials. Include them in templates or other fragments using the <code>&lt;fragment&gt;</code> tag.</p>
 		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- nav.fragment.html --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">fragment</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">nav</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">a</span> <span class="hljs-attr">href</span>=<span class="hljs-string">"./"</span>&gt;</span>Home<span class="hljs-tag">&lt;/<span class="hljs-name">a</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">a</span> <span class="hljs-attr">href</span>=<span class="hljs-string">"./about.html"</span>&gt;</span>About<span class="hljs-tag">&lt;/<span class="hljs-name">a</span>&gt;</span><br />  <span class="hljs-tag">&lt;/<span class="hljs-name">nav</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">fragment</span>&gt;</span></code></pre>
 		<p>Include it in a template:</p>
@@ -68,10 +82,44 @@
 			<li>A subdirectory can provide its own version to override the parent</li>
 		</ul>
 
+		<h2 id="global-files">Global Files</h2>
+		<p>Any file named <code>*.global.html</code> anywhere under the root directory is automatically loaded and its <code>&lt;content&gt;</code> blocks are injected into every page render. This is the right place to put site-wide scripts, meta tags, nav links, or anything else that should appear across all pages without touching every template or page file.</p>
+		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- analytics.global.html --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">content</span> <span class="hljs-attr">location</span>=<span class="hljs-string">"scripts"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"analytics.js"</span> <span class="hljs-attr">defer</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">content</span>&gt;</span></code></pre>
+		<p>The template just needs a matching <code>&lt;location&gt;</code> tag &mdash; the global file fills it automatically on every page.</p>
+
+		<h3>Priority</h3>
+		<p>When multiple <code>&lt;content&gt;</code> blocks &mdash; from global files, multiple global files, or the page itself &mdash; target the same location, a <code>priority</code> attribute controls their output order. Higher numbers come first. The default is <code>0</code>.</p>
+		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- framework.global.html --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">content</span> <span class="hljs-attr">location</span>=<span class="hljs-string">"scripts"</span> <span class="hljs-attr">priority</span>=<span class="hljs-string">"10"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"framework.js"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">content</span>&gt;</span><br /><br /><span class="hljs-comment">&lt;!-- analytics.global.html — priority defaults to 0 --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">content</span> <span class="hljs-attr">location</span>=<span class="hljs-string">"scripts"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"analytics.js"</span> <span class="hljs-attr">defer</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">content</span>&gt;</span></code></pre>
+		<p>Output: <code>framework.js</code> first (priority 10), then <code>analytics.js</code> (priority 0). The same <code>priority</code> attribute works on <code>&lt;content&gt;</code> blocks in page files too, so a page can insert content before or after global content in the same location.</p>
+
+		<h3>Locations Inside Page Content</h3>
+		<p>You can place <code>&lt;location&gt;</code> tags inside a page's <code>&lt;content&gt;</code> block. Global content fills those locations before the block is inserted into the template. This lets a page pull in a global snippet at a specific spot without knowing what the snippet contains.</p>
+		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- nav-links.global.html --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">content</span> <span class="hljs-attr">location</span>=<span class="hljs-string">"links"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">a</span> <span class="hljs-attr">href</span>=<span class="hljs-string">"./about.html"</span>&gt;</span>About<span class="hljs-tag">&lt;/<span class="hljs-name">a</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">content</span>&gt;</span><br /><br /><span class="hljs-comment">&lt;!-- nav.fragment.html — location tag pulls in the global links --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">fragment</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">nav</span>&gt;</span><br />    <span class="hljs-tag">&lt;<span class="hljs-name">location</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"links"</span> /&gt;</span><br />  <span class="hljs-tag">&lt;/<span class="hljs-name">nav</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">fragment</span>&gt;</span></code></pre>
+
+		<h2 id="fragments-vs-globals">Fragments vs. Global Files</h2>
+		<p>Fragments and global files both let you share HTML across pages, but they work in opposite directions.</p>
+		<p><strong>Fragments are a pull.</strong> The template (or another fragment) explicitly asks for one thing by name: <code>&lt;fragment name="nav" /&gt;</code>. The fragment file is a single reusable block of markup. Only what is asked for gets included, and where it lands is decided entirely by the caller.</p>
+		<p><strong>Global files are a push.</strong> A <code>*.global.html</code> file declares content and targets a location, and that content is automatically injected into every page render without the template needing to know it exists. You can have many global files each contributing to the same location, and a page can add its own content to that same location alongside them. The final output is all of those contributions merged and ordered by <code>priority</code>.</p>
+		<div class="table-wrapper mb">
+		<table>
+			<thead>
+				<tr><th></th><th>Fragments</th><th>Global Files</th></tr>
+			</thead>
+			<tbody>
+				<tr><td>Direction</td><td>Pull — caller decides what to include</td><td>Push — file injects itself automatically</td></tr>
+				<tr><td>How many per location</td><td>One (the named file)</td><td>Many — all globals targeting the same location are merged</td></tr>
+				<tr><td>Page can contribute too?</td><td>No — the fragment replaces the tag entirely</td><td>Yes — page <code>&lt;content&gt;</code> blocks merge with global content</td></tr>
+				<tr><td>Requires template change?</td><td>Yes — caller must add <code>&lt;fragment name="..." /&gt;</code></td><td>No — just add a <code>&lt;location&gt;</code> and the globals fill it</td></tr>
+				<tr><td>Good for</td><td>Reusable structural blocks (nav, footer, sidebar)</td><td>Site-wide injections (scripts, meta tags, nav links)</td></tr>
+			</tbody>
+		</table>
+		</div>
+
 		<h2 id="variables">Variables</h2>
-		<p>Use <code>{{variableName}}</code> syntax to insert dynamic values into templates and fragments.</p>
+		<p>Use <code>&#123;&#123;variableName&#125;&#125;</code> syntax to insert dynamic values into templates and fragments.</p>
 
 		<h3>Built-in Variables</h3>
+		<div class="table-wrapper mb">
 		<table>
 			<thead>
 				<tr>
@@ -80,19 +128,20 @@
 				</tr>
 			</thead>
 			<tbody>
-				<tr><td><code>{{pathToRoot}}</code></td><td>Relative path from the page to the root directory (e.g. <code>./</code>, <code>../</code>, <code>../../</code>)</td></tr>
-				<tr><td><code>{{year}}</code></td><td>Current four-digit year</td></tr>
-				<tr><td><code>{{date}}</code></td><td>Current date in ISO format (<code>YYYY-MM-DD</code>)</td></tr>
-				<tr><td><code>{{datetime}}</code></td><td>Full ISO 8601 datetime string</td></tr>
-				<tr><td><code>{{timestamp}}</code></td><td>Unix timestamp in milliseconds</td></tr>
-				<tr><td><code>{{version}}</code></td><td>Version from the root <code>package.json</code></td></tr>
-				<tr><td><code>{{env}}</code></td><td>Value of <code>NODE_ENV</code></td></tr>
+				<tr><td><code>&#123;&#123;pathToRoot&#125;&#125;</code></td><td>Relative path from the page to the root directory (e.g. <code>./</code>, <code>../</code>, <code>../../</code>)</td></tr>
+				<tr><td><code>&#123;&#123;year&#125;&#125;</code></td><td>Current four-digit year</td></tr>
+				<tr><td><code>&#123;&#123;date&#125;&#125;</code></td><td>Current date in ISO format (<code>YYYY-MM-DD</code>)</td></tr>
+				<tr><td><code>&#123;&#123;datetime&#125;&#125;</code></td><td>Full ISO 8601 datetime string</td></tr>
+				<tr><td><code>&#123;&#123;timestamp&#125;&#125;</code></td><td>Unix timestamp in milliseconds</td></tr>
+				<tr><td><code>&#123;&#123;version&#125;&#125;</code></td><td>Version from the root <code>package.json</code></td></tr>
+				<tr><td><code>&#123;&#123;env&#125;&#125;</code></td><td>Value of <code>NODE_ENV</code></td></tr>
 			</tbody>
 		</table>
+		</div>
 
 		<h3>Page Attributes as Variables</h3>
 		<p>Any attribute on the <code>&lt;page&gt;</code> tag is available as a variable in the template:</p>
-		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- page file --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">page</span> <span class="hljs-attr">title</span>=<span class="hljs-string">"My Page"</span> <span class="hljs-attr">author</span>=<span class="hljs-string">"Dustin"</span>&gt;</span>...<span class="hljs-tag">&lt;/<span class="hljs-name">page</span>&gt;</span><br /><br /><span class="hljs-comment">&lt;!-- template file --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">title</span>&gt;</span>{{title}}<span class="hljs-tag">&lt;/<span class="hljs-name">title</span>&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">meta</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"author"</span> <span class="hljs-attr">content</span>=<span class="hljs-string">"{{author}}"</span> /&gt;</span></code></pre>
+		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- page file --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">page</span> <span class="hljs-attr">title</span>=<span class="hljs-string">"My Page"</span> <span class="hljs-attr">author</span>=<span class="hljs-string">"Dustin"</span>&gt;</span>...<span class="hljs-tag">&lt;/<span class="hljs-name">page</span>&gt;</span><br /><br /><span class="hljs-comment">&lt;!-- template file --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">title</span>&gt;</span>&#123;&#123;title&#125;&#125;<span class="hljs-tag">&lt;/<span class="hljs-name">title</span>&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">meta</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"author"</span> <span class="hljs-attr">content</span>=<span class="hljs-string">"&#123;&#123;author&#125;&#125;"</span> /&gt;</span></code></pre>
 
 		<h3>Globals and State</h3>
 		<p>Additional variables can be provided through the <code>globals</code> and <code>state</code> configuration objects. Globals and state are merged with page attributes, with page attributes taking priority.</p>
@@ -101,7 +150,7 @@
 
 		<h3>Dot-Path Access</h3>
 		<p>Variables support dot notation for nested object access:</p>
-		<pre><code class="hljs xml">{{site.name}}<br />{{author.email}}</code></pre>
+		<pre><code class="hljs xml">&#123;&#123;site.name&#125;&#125;<br />&#123;&#123;author.email&#125;&#125;</code></pre>
 
 		<h2 id="conditionals">Conditionals</h2>
 		<p>Use <code>&lt;if&gt;</code> blocks to conditionally include content based on variable values.</p>
@@ -109,6 +158,7 @@
 
 		<h3>Supported Operators</h3>
 		<p>Conditions support a full expression syntax:</p>
+		<div class="table-wrapper mb">
 		<table>
 			<thead>
 				<tr>
@@ -126,13 +176,14 @@
 				<tr><td><code>( )</code></td><td>Grouping</td></tr>
 			</tbody>
 		</table>
+		</div>
 
 		<h3>Examples</h3>
 		<pre><code class="hljs xml"><span class="hljs-comment">&lt;!-- Truthy check --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">if</span> <span class="hljs-attr">condition</span>=<span class="hljs-string">"isLoggedIn"</span>&gt;</span>Welcome back!<span class="hljs-tag">&lt;/<span class="hljs-name">if</span>&gt;</span><br /><br /><span class="hljs-comment">&lt;!-- Negation --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">if</span> <span class="hljs-attr">condition</span>=<span class="hljs-string">"!isLoggedIn"</span>&gt;</span>Please log in.<span class="hljs-tag">&lt;/<span class="hljs-name">if</span>&gt;</span><br /><br /><span class="hljs-comment">&lt;!-- String comparison --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">if</span> <span class="hljs-attr">condition</span>=<span class="hljs-string">"env === 'production'"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"analytics.js"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">if</span>&gt;</span><br /><br /><span class="hljs-comment">&lt;!-- Compound conditions --&gt;</span><br /><span class="hljs-tag">&lt;<span class="hljs-name">if</span> <span class="hljs-attr">condition</span>=<span class="hljs-string">"isAdmin &amp;&amp; hasPermission"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">a</span> <span class="hljs-attr">href</span>=<span class="hljs-string">"/admin"</span>&gt;</span>Admin Panel<span class="hljs-tag">&lt;/<span class="hljs-name">a</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">if</span>&gt;</span></code></pre>
 
 		<h2 id="loops">Loops</h2>
 		<p>Use <code>&lt;foreach&gt;</code> blocks to iterate over arrays.</p>
-		<pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">foreach</span> <span class="hljs-attr">in</span>=<span class="hljs-string">"navLinks"</span> <span class="hljs-attr">as</span>=<span class="hljs-string">"link"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">a</span> <span class="hljs-attr">href</span>=<span class="hljs-string">"{{link.url}}"</span>&gt;</span>{{link.label}}<span class="hljs-tag">&lt;/<span class="hljs-name">a</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">foreach</span>&gt;</span></code></pre>
+		<pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">foreach</span> <span class="hljs-attr">in</span>=<span class="hljs-string">"navLinks"</span> <span class="hljs-attr">as</span>=<span class="hljs-string">"link"</span>&gt;</span><br />  <span class="hljs-tag">&lt;<span class="hljs-name">a</span> <span class="hljs-attr">href</span>=<span class="hljs-string">"&#123;&#123;link.url&#125;&#125;"</span>&gt;</span>&#123;&#123;link.label&#125;&#125;<span class="hljs-tag">&lt;/<span class="hljs-name">a</span>&gt;</span><br /><span class="hljs-tag">&lt;/<span class="hljs-name">foreach</span>&gt;</span></code></pre>
 		<p>The <code>in</code> attribute references an array variable and <code>as</code> names the loop variable. The loop variable supports dot-path access for object items.</p>
 
 		<p>Provide the array through globals or state:</p>
@@ -162,6 +213,7 @@
 
 		<h2 id="configuration">Configuration</h2>
 		<p>All templating options live under the <code>templating</code> key in your configuration file.</p>
+		<div class="table-wrapper mb">
 		<table>
 			<thead>
 				<tr>
@@ -179,6 +231,7 @@
 				<tr><td><code>maxFragmentDepth</code></td><td><code>10</code></td><td>Maximum fragment nesting depth</td></tr>
 			</tbody>
 		</table>
+		</div>
 
 		<h3>Development vs Production</h3>
 		<p>A common pattern is to use separate config files:</p>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kempo-server",
   "type": "module",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "A lightweight, zero-dependency, file based routing server.",
   "exports": {
     "./rescan": "./dist/rescan.js",
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "node scripts/build.js",
     "docs": "node dist/index.js -r ./docs",
-    "docs-src": "node dist/index.js -r ./docs-src",
+    "dev": "node dist/index.js -r ./docs-src",
     "spa": "node dist/index.js -r ./spa",
     "test": "npx kempo-test",
     "test:gui": "npx kempo-test --gui",

package/src/templating/index.js

@@ -3,6 +3,7 @@ import path from 'path';
 import {
   extractAttrs,
   extractContentBlocks,
+  mergeContentBlocks,
   replaceLocations,
   resolveVars,
   resolveIfs,
@@ -38,10 +39,33 @@ const loadVersion = rootDir => {
   }
 };
 
+/*
+  Walk Directory for *.global.html Files
+*/
+const walkGlobals = async dir => {
+  const entries = await readdir(dir, {withFileTypes: true});
+  const results = [];
+  for(const entry of entries){
+    const full = path.join(dir, entry.name);
+    if(entry.isDirectory()){
+      results.push(...await walkGlobals(full));
+    } else if(entry.name.endsWith('.global.html')){
+      results.push(full);
+    }
+  }
+  return results;
+};
+
+const loadGlobalContent = async rootDir => {
+  const files = await walkGlobals(rootDir);
+  const maps = await Promise.all(files.map(async f => extractContentBlocks(await readFile(f, 'utf8'))));
+  return mergeContentBlocks(...maps);
+};
+
 /*
   Render a Single Page
 */
-const renderPage = async (pageFilePath, rootDir, globals = {}, state = {}, maxDepth = 10) => {
+const renderPage = async (pageFilePath, rootDir, globals = {}, state = {}, maxDepth = 10, preloadedGlobalContent = null) => {
   const pageContent = await readFile(pageFilePath, 'utf8');
   const pageTagMatch = pageContent.match(/^[\s\S]*?<page\s([^>]*)>/);
   if(!pageTagMatch) throw new Error(`Invalid page file: missing <page> root element in ${pageFilePath}`);
@@ -49,11 +73,20 @@ const renderPage = async (pageFilePath, rootDir, globals = {}, state = {}, maxDe
   const templateName = pageAttrs.template || 'default';
   delete pageAttrs.template;
 
-  const contentBlocks = extractContentBlocks(pageContent);
   const pageDir = path.dirname(pageFilePath);
   const templateFile = findFileUpSync(`${templateName}.template.html`, pageDir, rootDir);
   if(!templateFile) throw new Error(`Template not found: ${templateName}.template.html (searched from ${pageDir} to ${rootDir})`);
 
+  const globalContent = preloadedGlobalContent ?? await loadGlobalContent(rootDir);
+  const rawPageBlocks = extractContentBlocks(pageContent);
+
+  // Allow <location> tags inside page content blocks to be filled by global content
+  const pageBlocks = {};
+  for(const [name, entries] of Object.entries(rawPageBlocks)){
+    pageBlocks[name] = entries.map(e => ({...e, html: replaceLocations(e.html, globalContent)}));
+  }
+
+  const contentBlocks = mergeContentBlocks(pageBlocks, globalContent);
   let templateHtml = readFileSync(templateFile, 'utf8');
 
   const findFragmentFile = name => {
@@ -115,14 +148,14 @@ const walkPages = async dir => {
   Render All Pages in a Directory
 */
 const renderDir = async (inputDir, outputDir, globals = {}, state = {}, maxDepth = 10) => {
-  const pages = await walkPages(inputDir);
+  const [pages, globalContent] = await Promise.all([walkPages(inputDir), loadGlobalContent(inputDir)]);
   let count = 0;
   for(const page of pages){
     const rel = path.relative(inputDir, page);
     const outRel = rel.replace(/\.page\.html$/, '.html');
     const outPath = path.join(outputDir, outRel);
     await mkdir(path.dirname(outPath), {recursive: true});
-    const html = await renderPage(page, inputDir, globals, state, maxDepth);
+    const html = await renderPage(page, inputDir, globals, state, maxDepth, globalContent);
     await writeFile(outPath, html, 'utf8');
     count++;
   }

package/src/templating/parse.js

@@ -16,25 +16,47 @@ const extractAttrs = tagString => {
 */
 const extractContentBlocks = xml => {
   const blocks = {};
-  const re = /<content(?:\s+location="([^"]*)")?\s*>([\s\S]*?)<\/content>/g;
+  const re = /<content(?:\s+([^>]*))?\s*>([\s\S]*?)<\/content>/g;
   let match;
   while((match = re.exec(xml)) !== null){
-    const name = match[1] || 'default';
-    blocks[name] = (blocks[name] || '') + match[2];
+    const attrs = extractAttrs(match[1] || '');
+    const name = attrs.location || 'default';
+    const priority = parseInt(attrs.priority || '0', 10);
+    if(!blocks[name]) blocks[name] = [];
+    blocks[name].push({html: match[2], priority});
   }
   return blocks;
 };
 
+/*
+  Content Block Merging
+*/
+const mergeContentBlocks = (...maps) => {
+  const merged = {};
+  for(const map of maps){
+    for(const [name, entries] of Object.entries(map)){
+      if(!merged[name]) merged[name] = [];
+      merged[name].push(...entries);
+    }
+  }
+  return merged;
+};
+
 /*
   Location Replacement
 */
+const resolveLocation = (entries) => {
+  if(!entries?.length) return null;
+  return [...entries].sort((a, b) => b.priority - a.priority).map(e => e.html).join('');
+};
+
 const replaceLocations = (html, contentMap) =>
   html
     .replace(/<location(?:\s+name="([^"]*)")?>([\s\S]*?)<\/location>/g, (_, name, fallback) =>
-      contentMap[name || 'default'] ?? fallback
+      resolveLocation(contentMap[name || 'default']) ?? fallback
     )
     .replace(/<location(?:\s+name="([^"]*)")?\s*\/>/g, (_, name) =>
-      contentMap[name || 'default'] ?? ''
+      resolveLocation(contentMap[name || 'default']) ?? ''
     );
 
 /*
@@ -274,6 +296,7 @@ const evalCondition = (expression, vars) => {
 export {
   extractAttrs,
   extractContentBlocks,
+  mergeContentBlocks,
   replaceLocations,
   stripFragmentWrapper,
   resolveVars,

package/tests/templating-parse.node-test.js

@@ -1,6 +1,7 @@
 import {
   extractAttrs,
   extractContentBlocks,
+  mergeContentBlocks,
   replaceLocations,
   stripFragmentWrapper,
   resolveVars,
@@ -26,13 +27,33 @@ export default {
   'extractContentBlocks extracts named blocks': ({pass, fail}) => {
     const xml = '<content location="main">Hello</content><content location="sidebar">World</content>';
     const blocks = extractContentBlocks(xml);
-    if(blocks.main !== 'Hello') return fail('main wrong');
-    if(blocks.sidebar !== 'World') return fail('sidebar wrong');
+    if(!Array.isArray(blocks.main) || blocks.main[0].html !== 'Hello') return fail('main wrong');
+    if(!Array.isArray(blocks.sidebar) || blocks.sidebar[0].html !== 'World') return fail('sidebar wrong');
+    pass();
+  },
+  'extractContentBlocks captures priority': ({pass, fail}) => {
+    const xml = '<content location="main" priority="5">hi</content>';
+    const blocks = extractContentBlocks(xml);
+    if(blocks.main[0].priority !== 5) return fail(`priority wrong: ${blocks.main[0].priority}`);
+    pass();
+  },
+  'extractContentBlocks defaults priority to 0': ({pass, fail}) => {
+    const xml = '<content location="main">hi</content>';
+    const blocks = extractContentBlocks(xml);
+    if(blocks.main[0].priority !== 0) return fail(`priority wrong: ${blocks.main[0].priority}`);
+    pass();
+  },
+  'mergeContentBlocks combines maps': ({pass, fail}) => {
+    const a = {main: [{html: 'A', priority: 0}]};
+    const b = {main: [{html: 'B', priority: 0}], sidebar: [{html: 'S', priority: 0}]};
+    const merged = mergeContentBlocks(a, b);
+    if(merged.main.length !== 2) return fail(`main length wrong: ${merged.main.length}`);
+    if(!merged.sidebar) return fail('sidebar missing');
     pass();
   },
   'replaceLocations fills named locations': ({pass, fail}) => {
     const html = '<location name="main" />';
-    const result = replaceLocations(html, {main: '<p>Hi</p>'});
+    const result = replaceLocations(html, {main: [{html: '<p>Hi</p>', priority: 0}]});
     if(result !== '<p>Hi</p>') return fail(`got: ${result}`);
     pass();
   },
@@ -44,10 +65,21 @@ export default {
   },
   'replaceLocations uses content over fallback': ({pass, fail}) => {
     const html = '<location name="main">fallback</location>';
-    const result = replaceLocations(html, {main: 'real'});
+    const result = replaceLocations(html, {main: [{html: 'real', priority: 0}]});
     if(result !== 'real') return fail(`got: ${result}`);
     pass();
   },
+  'replaceLocations orders by priority descending': ({pass, fail}) => {
+    const html = '<location name="scripts" />';
+    const entries = [
+      {html: 'low', priority: 1},
+      {html: 'high', priority: 10},
+      {html: 'mid', priority: 5}
+    ];
+    const result = replaceLocations(html, {scripts: entries});
+    if(result !== 'highmidlow') return fail(`got: ${result}`);
+    pass();
+  },
   'stripFragmentWrapper removes wrapping fragment tag': ({pass, fail}) => {
     const result = stripFragmentWrapper('<fragment name="nav"><nav>Hi</nav></fragment>');
     if(result !== '<nav>Hi</nav>') return fail(`got: ${result}`);
@@ -210,28 +242,30 @@ export default {
   },
   'extractContentBlocks defaults location to default': ({pass, fail}) => {
     const blocks = extractContentBlocks('<content>Hello</content>');
-    if(blocks.default !== 'Hello') return fail(`got: ${blocks.default}`);
+    if(!Array.isArray(blocks.default) || blocks.default[0].html !== 'Hello') return fail(`got: ${JSON.stringify(blocks.default)}`);
     pass();
   },
   'extractContentBlocks concatenates multiple contents to same location': ({pass, fail}) => {
     const xml = '<content location="main">A</content><content location="main">B</content>';
     const blocks = extractContentBlocks(xml);
-    if(blocks.main !== 'AB') return fail(`got: ${blocks.main}`);
+    if(blocks.main.length !== 2) return fail(`expected 2 entries, got: ${JSON.stringify(blocks.main)}`);
+    if(blocks.main[0].html !== 'A' || blocks.main[1].html !== 'B') return fail(`got: ${JSON.stringify(blocks.main)}`);
     pass();
   },
   'extractContentBlocks concatenates default contents': ({pass, fail}) => {
     const xml = '<content>A</content><content>B</content>';
     const blocks = extractContentBlocks(xml);
-    if(blocks.default !== 'AB') return fail(`got: ${blocks.default}`);
+    if(blocks.default.length !== 2) return fail(`expected 2 entries, got: ${JSON.stringify(blocks.default)}`);
+    if(blocks.default[0].html !== 'A' || blocks.default[1].html !== 'B') return fail(`got: ${JSON.stringify(blocks.default)}`);
     pass();
   },
   'replaceLocations defaults nameless location to default': ({pass, fail}) => {
-    const result = replaceLocations('<location />', {default: 'Hi'});
+    const result = replaceLocations('<location />', {default: [{html: 'Hi', priority: 0}]});
     if(result !== 'Hi') return fail(`got: ${result}`);
     pass();
   },
   'replaceLocations defaults nameless block location to default': ({pass, fail}) => {
-    const result = replaceLocations('<location>fallback</location>', {default: 'Hi'});
+    const result = replaceLocations('<location>fallback</location>', {default: [{html: 'Hi', priority: 0}]});
     if(result !== 'Hi') return fail(`got: ${result}`);
     pass();
   },

package/tests/templating-render.node-test.js

@@ -184,5 +184,96 @@ export default {
       if(!html.includes(String(new Date().getFullYear()))) return fail(`year missing: ${html}`);
       pass();
     });
+  },
+  'renderPage injects global content into template location': async ({pass, fail}) => {
+    await withTempDir(async dir => {
+      await setupFiles(dir, {
+        'default.template.html': '<head><location name="head" /></head><body><location name="main" /></body>',
+        'site.global.html': '<content location="head"><meta charset="utf-8"></content>',
+        'index.page.html': '<page template="default"><content location="main">hello</content></page>'
+      });
+      const html = await renderPage(path.join(dir, 'index.page.html'), dir);
+      if(!html.includes('<meta charset="utf-8">')) return fail(`global head missing: ${html}`);
+      if(!html.includes('hello')) return fail(`page content missing: ${html}`);
+      pass();
+    });
+  },
+  'renderPage merges page and global content into same location': async ({pass, fail}) => {
+    await withTempDir(async dir => {
+      await setupFiles(dir, {
+        'default.template.html': '<location name="scripts" />',
+        'site.global.html': '<content location="scripts"><script src="analytics.js"></script></content>',
+        'index.page.html': '<page template="default"><content location="scripts"><script src="page.js"></script></content></page>'
+      });
+      const html = await renderPage(path.join(dir, 'index.page.html'), dir);
+      if(!html.includes('analytics.js')) return fail(`global script missing: ${html}`);
+      if(!html.includes('page.js')) return fail(`page script missing: ${html}`);
+      pass();
+    });
+  },
+  'renderPage respects priority ordering — higher number first': async ({pass, fail}) => {
+    await withTempDir(async dir => {
+      await setupFiles(dir, {
+        'default.template.html': '<location name="scripts" />',
+        'site.global.html': '<content location="scripts" priority="10">FIRST</content><content location="scripts" priority="1">LAST</content>',
+        'index.page.html': '<page template="default"></page>'
+      });
+      const html = await renderPage(path.join(dir, 'index.page.html'), dir);
+      if(html.indexOf('FIRST') > html.indexOf('LAST')) return fail(`wrong order: ${html}`);
+      pass();
+    });
+  },
+  'renderPage page content priority beats global at same location': async ({pass, fail}) => {
+    await withTempDir(async dir => {
+      await setupFiles(dir, {
+        'default.template.html': '<location name="scripts" />',
+        'site.global.html': '<content location="scripts" priority="0">global</content>',
+        'index.page.html': '<page template="default"><content location="scripts" priority="5">page</content></page>'
+      });
+      const html = await renderPage(path.join(dir, 'index.page.html'), dir);
+      if(html.indexOf('page') > html.indexOf('global')) return fail(`page should come before global: ${html}`);
+      pass();
+    });
+  },
+  'renderPage fills locations inside page content from globals': async ({pass, fail}) => {
+    await withTempDir(async dir => {
+      await setupFiles(dir, {
+        'default.template.html': '<location name="main" />',
+        'site.global.html': '<content location="badge"><span class="badge">NEW</span></content>',
+        'index.page.html': '<page template="default"><content location="main"><h1>Title</h1><location name="badge" /></content></page>'
+      });
+      const html = await renderPage(path.join(dir, 'index.page.html'), dir);
+      if(!html.includes('<span class="badge">NEW</span>')) return fail(`badge missing: ${html}`);
+      pass();
+    });
+  },
+  'renderPage loads globals from subdirectories': async ({pass, fail}) => {
+    await withTempDir(async dir => {
+      await setupFiles(dir, {
+        'default.template.html': '<location name="head" /><location name="main" />',
+        'sub/site.global.html': '<content location="head">subglobal</content>',
+        'index.page.html': '<page template="default"><content location="main">x</content></page>'
+      });
+      const html = await renderPage(path.join(dir, 'index.page.html'), dir);
+      if(!html.includes('subglobal')) return fail(`subdir global missing: ${html}`);
+      pass();
+    });
+  },
+  'renderDir applies global content to all pages': async ({pass, fail}) => {
+    await withTempDir(async dir => {
+      await setupFiles(dir, {
+        'default.template.html': '<location name="head" /><location name="main" />',
+        'site.global.html': '<content location="head"><meta name="global"></content>',
+        'index.page.html': '<page template="default"><content location="main">home</content></page>',
+        'about.page.html': '<page template="default"><content location="main">about</content></page>'
+      });
+      const outDir = path.join(dir, 'out');
+      await renderDir(dir, outDir);
+      const home = await readFile(path.join(outDir, 'index.html'), 'utf8');
+      const about = await readFile(path.join(outDir, 'about.html'), 'utf8');
+      if(!home.includes('<meta name="global">')) return fail(`home missing global: ${home}`);
+      if(!about.includes('<meta name="global">')) return fail(`about missing global: ${about}`);
+      pass();
+    });
   }
 };