@etchteam/dash
v1.1.1
Published
A tiny HTML build tool with zero dependencies
Keywords
Readme
A tiny build tool that adds layouts and frontmatter to HTML.
Installation
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.
Usage
Build
Build all HTML pages into the dist/ directory:
dash build--script
Use 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
Serve the dist/ directory as a static site. Clean URLs are supported automatically — /about will serve dist/about/index.html.
dash serve--port
Change the port (defaults to 3000):
dash serve --port 8080--watch
Build first, then serve and automatically rebuild when HTML pages or referenced assets (CSS, JS, images, fonts) change:
dash serve --watch--script
Serve with a custom transform script, applied to the initial build and every rebuild:
dash serve --watch --script transform.jsProgrammatic
The 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);How it works
Layouts
Create layout files with the naming convention layout.{name}.html:
layout.default.html
layout.article.htmlInside 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.
Pages
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.
Frontmatter
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.
Assets
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.
Similar tools
For more complex build needs, consider: