A tiny build tool that adds layouts and frontmatter to HTML.
Dash requires Bun to run.
bun add @etchteam/dashOr with npm:
npm install @etchteam/dashOr copybuild.js source code into your project. The entire build tool is a single file.
Build all HTML pages into the dist/ directory:
dash buildUse a custom transform script to modify content during build. The script should default-export a function that receives frontmatter and content and returns the transformed content:
// transform.js
export default function transform({
frontmatter,
content
}) {
// Transform content however you like, e.g. process markdown
return processedContent;
}dash build --script transform.jsServe the dist/ directory as a static site. Clean URLs are supported automatically — /about will serve dist/about/index.html.
dash serveChange the port (defaults to 3000):
dash serve --port 8080Build first, then serve and automatically rebuild when HTML pages or referenced assets (CSS, JS, images, fonts) change:
dash serve --watchServe with a custom transform script, applied to the initial build and every rebuild:
dash serve --watch --script transform.jsThe build function can be imported and used as part of an existing script or build pipeline:
import { build } from '@etchteam/dash';
await build({
transform: ({ frontmatter, content }) => {
// Transform content, e.g. process markdown
return processedContent;
}
});All options are optional — calling await build() runs a standard build. Pass transform to modify content per page, or clean: false to build without wiping dist/ first.
The startServer function is also available for programmatic use:
import { startServer } from '@etchteam/dash/serve';
startServer(8080);Create layout files with the naming convention layout.{name}.html:
layout.default.html
layout.article.html
Inside a layout, use three-dash HTML comments as placeholders:
<!DOCTYPE html>
<html>
<head>
<title><!--- title ---></title>
</head>
<body>
<!--- content --->
</body>
</html><!--- content ---> is a special placeholder that gets replaced with the page content. All other placeholders are replaced with values from the page's frontmatter.
HTML files use a frontmatter-style comment block at the top:
<!---
title: My Page
layout: article
--->
<h1>Hello</h1>
<p>This is my page content.</p>The layout key specifies which layout file to use. If omitted, layout.default.html is used.
Three-dash HTML comments at the top of a file. Key-value pairs, one per line:
<!---
title: Hello World
description: A simple page
author: Etch
--->These values replace matching <!--- key ---> placeholders in the layout. Because the frontmatter uses valid HTML comment syntax, your pages still work as plain HTML files in the browser.
Any local asset file like JavaScript, CSS, images or fonts referenced from a page or its layout via src or href get copied into dist/ at the same relative path it is referenced from. A shared asset is copied once per build.
For more complex build needs, consider: