HTML Pages Plugin

A plugin for staticbolt that serves and builds pages from a pages directory. It handles both static routes and dynamic routes.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install another package.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { htmlPagesPlugin } from "@staticbolt/core/plugins";

export default defineConfig({
  plugins: [
    htmlPagesPlugin({
      // Relative to the project root
      pagesDir: "./pages", // (default)

      // Relative to the output directory
      outputDir: "./", // (default)
    }),
  ],
});

Options

pagesDir

• Type: string
• Default: "./pages"

The directory that holds your page files, relative to the project root.

outputDir

• Type: string
• Default: "./"

The directory that the compiled HTML pages are written to, relative to the configured output directory. By default they go to the root of the output directory.

Static routes

An HTML or Markdown file in the pages directory with no dynamic segments is a static route.

Dynamic routes

Dynamic routes let you generate multiple HTML pages from a single template file. The plugin expands the template at build time into one output page per route.

File naming

To mark a page as a dynamic route, wrap one or more path segments in square brackets.

pages/users/[id].html             ->  /users/1.html, /users/2.html, ...
pages/blog/[category]/index.html  ->  /blog/news/, /blog/guides/, ...

To match multiple segments with a single parameter, use the spread syntax.

pages/docs/[...slug].html      -> /docs/getting-started.html, /docs/api/reference.html, ...

Defining routes with getStaticPaths

Inside the template file, add a <script params> tag that exports a getStaticPaths function. It must return an array of route entries. Each entry contains a params object whose keys match the dynamic segments in the file name.

<h1>User {{ $params.id }}</h1>
<p>Hello, {{ $props.name }}</p>

<script params>
  export async function getStaticPaths() {
    return [
      { params: { id: "1" }, props: { name: "Alice" } },
      { params: { id: "2" }, props: { name: "Bob" } },
    ];
  }
</script>

The props object is optional. Both params and props values are available as template placeholders in the HTML.

getStaticPaths return type

The function must return an array where each item matches the following shape.

type GetStaticPathsResult = {
  params: Record<string, string>;
  props?: Record<string, string>;
}[];

Both params and props values must be strings.

Placeholders

The {{ }} syntax evaluates any JavaScript expression. Inside it, $params and $props hold the params and props values of the route.