${vars.title}
-
-
+ const children = render(html`
+
+
+
-
+
${typeof innerChildren === 'string'
- ? html([innerChildren])
- : innerChildren /* Support both uhtml and string children. Optional. */
+ ? html``
+ : innerChildren
}
-
-
- `
+ `)
const rootArgs = { ...rest, children }
return defaultRootLayout(rootArgs)
}
+
+export default blogLayout
```
Now the `blog.layout.js` becomes a nested layout of `root.layout.js`. No magic, just functions.
-Alternatively, you could compose your layouts from re-usable template functions and strings. If you find your layouts nesting more than one or two levels, perhaps composition would be a better strategy.
+Alternatively, you could compose your layouts from re-usable template functions and strings.
+If you find your layouts nesting more than one or two levels, perhaps composition would be a better strategy.
### Layout styles
You can create a `${layout-name}.layout.css` next to any layout file.
+While the layout file can live anywhere in `src`, the layout style must live next to the associated layout file.
```css
/* /layouts/article.layout.css */
@@ -566,24 +654,25 @@ You can create a `${layout-name}.layout.css` next to any layout file.
Layout styles are loaded on all pages that use that layout.
Layout styles are bundled with [`esbuild`][esbuild] and can bundle relative and `npm` css using css `@import` statements.
-### Layout JS Bundles
+### Layout TS/JS Bundles
-You can create a `${layout-name}.layout.client.js` next to any layout file.
+You can create a `${layout-name}.layout.client.ts` or `${layout-name}.layout.client.js` next to any layout file.
+While the layout file can live anywhere in `src`, the layout client bundles must live next to the associated layout file.
-```js
-/* /layouts/article.layout.client.js */
+```typescript
+/* /layouts/article.layout.client.ts */
console.log('I run on every page rendered with the \'article\' layout')
/* This layout client is included in every page rendered with the 'article' layout */
```
-Layout js bundles are loaded on all pages that use that layout.
-Layout js bundles are bundled with [`esbuild`][esbuild] and can bundle relative and `npm` modules using ESM `import` statements.
+Layout ts/js bundles are loaded on all pages that use that layout.
+Layout ts/js bundles are bundled with [`esbuild`][esbuild] and can bundle relative and `npm` modules using ESM `import` statements.
-### Nested layout JS bundles and styles
+### Nested layout TS/JS bundles and styles
-If you create a nested layout that imports another layout file, **and** that imported layout has a layout style and/or layout js bundle, there is no magic that will include those layout styles and clients into the importing layout. To include those layout styles and clients into an additional layout, just import them into the additional layout client and style files. For example:
+If you create a nested layout that imports another layout file, **and** that imported layout has a layout style and/or layout js bundle, there is no magic that will include those layout styles and clients into the importing layout. To include those layout styles and clients into an additional layout, just import them into the additional layout client and style files. For example, if `article.layout.ts` wraps `root.layout.ts`, you must do the following:
```css
/* article.layout.css */
@@ -592,41 +681,43 @@ If you create a nested layout that imports another layout file, **and** that imp
This will include the layout style from the `root` layout in the `article` layout style.
-```js
-/* article.layout.client.js */
-import './root.layout.client.js'
+```typescript
+/* article.layout.client.ts */
+import './root.layout.client.ts'
```
-These imports will include the `root.layout.js` layout assets into the `blog.layout.js` asset files.
+Adding these imports will include the `root.layout.ts` layout assets into the `blog.layout.ts` asset files.
## Static assets
-All static assets in the `src` directory are copied 1:1 to the `public` directory. Any file in the `src` directory that doesn't end in `.js`, `.css`, `.html`, or `.md` is copied to the `dest` directory.
+All static assets in the `src` directory are copied 1:1 to the `public` directory. Any file in the `src` directory that doesn't end in `.ts`, `.js`, `.css`, `.html`, or `.md` is copied to the `dest` directory.
### `--eject` flag
-The `--eject` (or `-e`) flag extracts top-bun's default layout, global CSS, and client-side JavaScript into your source directory. This allows you to fully customize these files while maintaining the same functionality.
+The `--eject` (or `-e`) flag extracts DOMStack's default layout, global CSS, and client-side JavaScript into your source directory. This allows you to fully customize these files while maintaining the same functionality.
-When you run `top-bun --eject`, it will:
+When you run `domstack --eject`, it will:
1. Create a default root layout file at `layouts/root.layout.js` (or `.mjs` depending on your package.json type)
2. Create a default global CSS file at `globals/global.css`
-3. Create a default client-side JavaScript file at `globals/global.client.js` (or `.mjs`)
+3. Create a default client-side JavaScript file at `globals/global.client.js`
4. Add the necessary dependencies to your package.json:
- mine.css
- - uhtml-isomorphic
+ - preact
+ - htm
+ - preact-render-to-string
- highlight.js
-This is useful when you want to heavily customize the default theme or behavior while still leveraging top-bun's core functionality.
+It is recomended to eject early in your project so that you can customize the root layout as you see fit, and de-couple yourself from potential unwanted changes in the default layout as new versions of DOMStack are released.
### `--copy` directories
You can specify directories to copy into your `dest` directory using the `--copy` flag. Everything in those directories will be copied as-is into the destination, including js, css, html and markdown, preserving the internal directory structure. Conflicting files are not detected or reported and will cause undefined behavior.
-Copy folders must live **outside** of the `dest` directory. Copy directories can be in the src directory allowing for nested builds. In this case they are added to the ignore glob and ignored by the rest of `top-bun`.
+Copy folders must live **outside** of the `dest` directory. Copy directories can be in the src directory allowing for nested builds. In this case they are added to the ignore glob and ignored by the rest of `domstack`.
-This is useful when you have legacy or archived site content that you want to include in your site, but don't want `top-bun` to process or modify it.
-In general, static content should live in your primary `src` directory, however for merging in old static assets over your top-bun build is sometimes easier to reason about when it's kept in a separate folder and isn't processed in any way.
+This is useful when you have legacy or archived site content that you want to include in your site, but don't want `domstack` to process or modify it.
+In general, static content should live in your primary `src` directory, however for merging in old static assets over your domstack build is sometimes easier to reason about when it's kept in a separate folder and isn't processed in any way.
For example:
@@ -656,56 +747,49 @@ public/
Template files let you write any kind of file type to the `dest` folder while customizing the contents of that file with access to the site [Variables](#variables) object, or inject any other kind of data fetched at build time. Template files can be located anywhere and look like:
```bash
-name-of-template.txt.template.js
-
-${name-portion}.template.js
+name-of-template.txt.template.ts
+${name-portion}.template.ts
```
-Template files are a `js` file that default exports one of the following sync/async functions:
+Template files are a `ts`/`js` file that default exports one of the following sync/async functions:
### Simple string template
A function that returns a string. The `name-of-template.txt` portion of the template file name becomes the file name of the output file.
-```js
-/**
- * @template T
- * @typedef {import('top-bun').TemplateFunction} TemplateFunction
- */
-
-/**
- * @type {TemplateFunction<{
- * foo: string,
- * testVar: string
- * }>}
- */
-export default async ({
+```typescript
+// name-of-template.txt.template.ts
+import type { TemplateFunction } from '@domstack/static'
+
+interface TemplateVars {
+ foo: string;
+ testVar: string;
+}
+
+const simpleTemplate: TemplateFunction = async ({
vars: {
- foo
+ foo,
+ testVar
}
}) => {
- return `{Hello world
+ return `Hello world
-This is just a file with access to global vars: ${foo}
-`
+This is just a file with access to global vars: ${foo}`
}
+
+export default simpleTemplate
```
### Object template
A function that returns a single object with a `content` and `outputName` entries. The `outputName` overrides the name portion of the template file name.
-```js
-/**
- * @template T
- * @typedef {import('top-bun').TemplateFunction} TemplateFunction
- */
-
-/**
- * @type {TemplateFunction<{
- * foo: string,
- * }>}
- */
+```typescript
+import type { TemplateFunction } from '@domstack/static'
+
+interface TemplateVars {
+ foo: string;
+}
export default async ({
vars: { foo }
}) => ({
@@ -720,24 +804,20 @@ This is just a file with access to global vars: ${foo}`,
A function that returns an array of objects with a `content` and `outputName` entries. This template file generates more than one file from a single template file.
-```js
-/**
- * @template T
- * @typedef {import('top-bun').TemplateFunction} TemplateFunction
- */
-
-/**
- * @type {TemplateFunction<{
- * foo: string,
- * testVar: string
- * }>}
- */
-export default async function objectArrayTemplate ({
+```typescript
+import type { TemplateFunction } from '@domstack/static'
+
+interface TemplateVars {
+ foo: string;
+ testVar: string;
+}
+
+const objectArrayTemplate: TemplateFunction = async ({
vars: {
foo,
testVar
}
-}) {
+}) => {
return [
{
content: `Hello world
@@ -753,23 +833,23 @@ This is just a file with access to global vars: ${testVar}`,
}
]
}
+
+export default objectArrayTemplate
```
### AsyncIterator template
An [AsyncIterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator) that `yields` objects with `content` and `outputName` entries.
-```js
-/**
- * @template T
- * @typedef {import('top-bun').TemplateAsyncIterator} TemplateAsyncIterator
- */
-
-/** @type {TemplateAsyncIterator<{
- * foo: string,
- * testVar: string
- * }>} */
-export default async function * ({
+```typescript
+import type { TemplateAsyncIterator } from '@domstack/static'
+
+interface TemplateVars {
+ foo: string;
+ testVar: string;
+}
+
+const templateIterator: TemplateAsyncIterator = async function * ({
vars: {
foo,
testVar
@@ -780,7 +860,7 @@ export default async function * ({
content: `Hello world
This is just a file with access to global vars: ${foo}`,
- outputName: 'async-iterator-1.txt'
+ outputName: 'yielded-1.txt'
}
// Second item
@@ -788,9 +868,11 @@ This is just a file with access to global vars: ${foo}`,
content: `Hello world again
This is just a file with access to global vars: ${testVar}`,
- outputName: 'async-iterator-2.txt'
+ outputName: 'yielded-2.txt'
}
}
+
+export default templateIterator
```
### RSS Feed Template Example
@@ -799,43 +881,37 @@ Templates receive the standard variables available to pages, so its possible to
The following example shows how to generate an [RSS](https://www.rssboard.org) and [JSON feed](https://www.jsonfeed.org) of the last 10 date sorted pages with the `blog` layout using the AsyncIterator template type.
-```js
+```typescript
import pMap from 'p-map'
-// @ts-ignore
import jsonfeedToAtom from 'jsonfeed-to-atom'
+import type { TemplateAsyncIterator } from '@domstack/static'
+
+interface TemplateVars {
+ title: string;
+ layout: string;
+ siteName: string;
+ homePageUrl: string;
+ authorName: string;
+ authorUrl: string;
+ authorImgUrl?: string;
+ siteDescription: string;
+ language: string;
+}
-/**
- * @template T
- * @typedef {import('top-bun').TemplateAsyncIterator} TemplateAsyncIterator
- */
-
-/** @type {TemplateAsyncIterator<{
- * title: string,
- * layout: string,
- * siteName: string,
- * homePageUrl: string,
- * authorName: string,
- * authorUrl: string,
- * authorImgUrl: string,
- * publishDate: string,
- * siteDescription: string
- * }>}
-*/
-export default async function * feedsTemplate ({
+const feedsTemplate: TemplateAsyncIterator = async function * ({
vars: {
siteName,
+ siteDescription,
homePageUrl,
+ language = 'en-us',
authorName,
authorUrl,
authorImgUrl,
- siteDescription
},
pages
}) {
const blogPosts = pages
- // @ts-ignore
.filter(page => page.pageInfo.path.startsWith('blog/') && page.vars['layout'] === 'blog')
- // @ts-ignore
.sort((a, b) => new Date(b.vars.publishDate) - new Date(a.vars.publishDate))
.slice(0, 10)
@@ -871,18 +947,20 @@ export default async function * feedsTemplate ({
outputName: './feeds/feed.xml'
}
}
+
+export default feedsTemplate
```
## Global Assets
-There are a few important (and optional) global assets that live anywhere in the `src` directory. If duplicate named files that match the global asset file name pattern are found, a build error will occur until the duplicate file is removed.
+There are a few important (and optional) global assets that live anywhere in the `src` directory. If duplicate named files that match the global asset file name pattern are found, a build error will occur until the duplicate file error is resolved.
-### `global.vars.js`
+### `global.vars.ts`
-The `global.vars.js` file should `export default` a variables object or a (sync or async) function that returns a variable object.
+The `global.vars.ts` or `global.vars.js` file should `export default` a variables object or a (sync or async) function that returns a variable object.
The variables in this file are available to all pages, unless the page sets a variable with the same key, taking a higher precedence.
-```js
+```typescript
export default {
siteName: 'The name of my website',
authorName: 'Mr. Wallace'
@@ -891,22 +969,25 @@ export default {
#### `browser` variable
-`global.vars.js` can uniquely export a `browser` object. These object variables are made available in all js bundles. The `browser` export can be an object, or a sync/async function that returns an object.
+`global.vars.ts` can uniquely export a `browser` object. These object variables are made available in all js bundles. The `browser` export can be an object, or a sync/async function that returns an object.
-```js
+```typescript
export const browser = {
- 'process.env.TRANSPORT': transport,
- 'process.env.HOST': host
+ 'process.env.TRANSPORT': 'http',
+ 'process.env.HOST': 'localhost'
}
```
The exported object is passed to esbuild's [`define`](https://esbuild.github.io/api/#define) options and is available to every js bundle.
-### `global.client.js`
+> [!WARNING]
+> Setting `define` in [`esbuild.settings.ts`](#esbuild-settingsts) while also using the `browser` export will throw an error. Use one or the other.
+
+### `global.client.ts`
This is a script bundle that is included on every page. It provides an easy way to inject analytics, or other small scripts that every page should have. Try to minimize what you put in here.
-```js
+```typescript
console.log('I run on every page in the site!')
```
@@ -916,31 +997,170 @@ This is a global stylesheet that every page will use.
Any styles that need to be on every single page should live here.
Importing css from `npm` modules work well here.
-### `esbuild.settings.js`
+### `global.data.js`
+
+The `global.data.js` (or `.ts`, `.mjs`, etc.) file is an optional file that can live anywhere in your `src` tree β like all global assets, the first one found wins and duplicates warn. It runs **once per build**, after all pages are initialized and before rendering begins.
+
+It receives a fully resolved `PageData[]` array and returns an object that is stamped onto every page's vars β making the derived data available to every page, layout, and template.
+
+```typescript
+import type { AsyncGlobalDataFunction } from '@domstack/static'
+import { html } from 'htm/preact'
+import { render } from 'preact-render-to-string'
+
+type GlobalData = {
+ blogPostsHtml: string
+}
+
+const buildGlobalData: AsyncGlobalDataFunction = async ({ pages }) => {
+ const blogPosts = pages
+ .filter(p => p.vars?.layout === 'blog' && p.vars?.publishDate)
+ .sort((a, b) => new Date(b.vars.publishDate) - new Date(a.vars.publishDate))
+ .slice(0, 5)
+
+ const blogPostsHtml = render(html`
+ ` or `AsyncGlobalDataFunction` to type the function where `T` is the shape of the object you return.
+
+### `esbuild.settings.ts`
This is an optional file you can create anywhere.
-It should export a default sync or async function that accepts a single argument (the esbuild settings object generated by top-bun) and returns a modified build object.
+It should export a default sync or async function that accepts a single argument (the esbuild settings object generated by domstack) and returns a modified build object.
Use this to customize the esbuild settings directly.
-You can break top-bun with this, so be careful.
+You can break domstack with this, so be careful.
Here is an example of using this file to polyfill node builtins in the browser bundle:
-```js
+```typescript
import { polyfillNode } from 'esbuild-plugin-polyfill-node'
+// BuildOptions re-exported from esbuild
+import type { BuildOptions } from '@domstack/static'
-export default async function esbuildSettingsOverride (esbuildSettings) {
- esbuildSettings.plugins = [
- polyfillNode(),
- ]
+const esbuildSettingsOverride = async (esbuildSettings: BuildOptions): Promise => {
+ esbuildSettings.plugins = [polyfillNode()]
return esbuildSettings
}
+
+export default esbuildSettingsOverride
```
+Important esbuild settings you may want to set here are:
+
+- [target](https://esbuild.github.io/api/#target) - Set the `target` to make `esbuild` run a few small transforms on your CSS and JS code.
+- [jsx](https://esbuild.github.io/api/#jsx) - Unset this if you want default react transform.
+- [jsxImportSource](https://esbuild.github.io/api/#jsx-import-source) - Unset this if you want default react transform.
+- [define](https://esbuild.github.io/api/#define) - Define compile-time constants for js bundles. Note: setting `define` here conflicts with the [`browser` export](#browser-variable) in `global.vars.ts` and will throw an error if both are set.
+
+### `markdown-it.settings.ts`
+
+This is an optional file you can create anywhere.
+It should export a default sync or async function that accepts a single argument (the markdown-it instance configured by domstack) and returns a modified markdown-it instance.
+Use this to add custom markdown-it plugins or modify the parser configuration.
+Here are some examples:
+
+```typescript
+import markdownItContainer from 'markdown-it-container'
+import markdownItPlantuml from 'markdown-it-plantuml'
+import type { MarkdownIt } from 'markdown-it'
+
+const markdownItSettingsOverride = async (md: MarkdownIt) => {
+ // Add custom plugins
+ md.use(markdownItContainer, 'spoiler', {
+ validate: (params: string) => {
+ return params.trim().match(/^spoiler\s+(.*)$/) !== null
+ },
+ render: (tokens: any[], idx: number) => {
+ const m = tokens[idx].info.trim().match(/^spoiler\s+(.*)$/)
+ if (tokens[idx].nesting === 1) {
+ return '\n'
+ }
+ }
+ })
+
+ md.use(markdownItPlantuml)
+
+ return md
+}
+
+export default markdownItSettingsOverride
+```
+
+```typescript
+import markdownIt, { MarkdownIt } from 'markdown-it'
+import myCustomPlugin from './my-custom-plugin'
+
+const markdownItSettingsOverride = async (md: MarkdownIt) => {
+ // Create a new instance with different settings
+ const newMd = markdownIt({
+ html: false, // Disable HTML tags in source
+ breaks: true, // Convert \n to
+ linkify: false, // Disable auto-linking + }) + + // Add only the plugins you want + newMd.use(myCustomPlugin) + + return newMd +} + +export default markdownItSettingsOverride +``` + +By default, DOMStack ships with the following markdown-it plugins enabled: + +- [markdown-it](https://github.com/markdown-it/markdown-it) +- [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote) +- [markdown-it-highlightjs](https://github.com/valeriangalliat/markdown-it-highlightjs) +- [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) +- [markdown-it-sub](https://github.com/markdown-it/markdown-it-sub) +- [markdown-it-sup](https://github.com/markdown-it/markdown-it-sup) +- [markdown-it-deflist](https://github.com/markdown-it/markdown-it-deflist) +- [markdown-it-ins](https://github.com/markdown-it/markdown-it-ins) +- [markdown-it-mark](https://github.com/markdown-it/markdown-it-mark) +- [markdown-it-abbr](https://github.com/markdown-it/markdown-it-abbr) +- [markdown-it-task-lists](https://github.com/revin/markdown-it-task-lists) +- [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) +- [markdown-it-attrs](https://github.com/arve0/markdown-it-attrs) +- [markdown-it-table-of-contents](https://github.com/cmaas/markdown-it-table-of-contents) + ## Variables -Pages, Layouts, and `postVars` all receive an object with the following parameters: +Pages and Layouts receive an object with the following parameters: -- `vars`: An object with the variables of `global.vars.js`, `page.vars.js`, and any front-matter,`vars` exports and `postVars` from the page merged together. -- `pages`: An array of [`PageData`](https://github.com/bcomnes/top-bun/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. +- `vars`: An object with the variables of `global.vars.ts`, `global.data.js`, `page.vars.ts`, and any front-matter or `vars` exports from the page merged together. +- `pages`: An array of [`PageData`](https://github.com/bcomnes/d omstack/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. - `page`: An object of the page being rendered with the following parameters: - `type`: The type of page (`md`, `html`, or `js`) - `path`: The directory path for the page. @@ -953,77 +1173,29 @@ Pages, Layouts, and `postVars` all receive an object with the following paramete Template files receive a similar set of variables: -- `vars`: An object with the variables of `global.vars.js` -- `pages`: An array of [`PageData`](https://github.com/bcomnes/top-bun/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. +- `vars`: An object with the variables of `global.vars.ts` +- `pages`: An array of [`PageData`](https://github.com/bcomnes/domstack/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. - `template`: An object of the template file data being rendered. -Where `T` is your set of variables in the `vars` object. - -### `postVars` post processing variables (Advanced) {#postVars} - -In `page.vars.js` files, you can export a `postVars` sync/async function that returns an object. This function receives the same variable set as pages and layouts. Whatever object is returned from the function is merged into the final `vars` object and is available in the page and layout. This is useful if you want to apply advanced rendering page introspection and insert it into a markdown document (for example, the last few blog posts on a markdown page.) - -For example: - -```js -// page.vars.js -import { html, render } from 'uhtml-isomorphic' - -export async function postVars ({ - pages -}) { - const blogPosts = pages - .filter(page => page.vars.layout === 'article') - .sort((a, b) => new Date(b.vars.publishDate) - new Date(a.vars.publishDate)) - .slice(0, 5) +### Derived global data (Advanced) - const blogpostsHtml = render(String, html`**
+- `T` - The type of variables passed to the page (required)
+- `U` - The return type of the page function (optional, defaults to `any`)
-export const vars = {
- message: 'TypeScript pages are easy!'
-}
+**LayoutFunction**
+- `T` - The type of variables passed to the layout (required)
+- `U` - The type of content received from pages as `children` (optional, defaults to `any`)
+- `V` - The return type of the layout function (optional, defaults to `string`)
-const page: PageFunction = async ({ vars }) => {
- return `
+ children: Array
}
-const layout: LayoutFunction = ({ vars, scripts, styles, children }) => {
- return render(String, html`
-
-
-
- ${vars.title ? `${vars.title} | ` : ''}${vars.siteName}
- ${styles?.map(style => html``)}
- ${scripts?.map(script => html``)}
-
-
- ${children}
-
-
- `)
-}
+// Page returns VDOM
+const page: PageFunction<{title: string}, VDOMNode> = ({ vars }) => ({
+ type: 'h1',
+ props: {},
+ children: [vars.title]
+})
-export default layout
+// Layout accepts VDOM, returns HTML string
+const layout: LayoutFunction<{site: string}, VDOMNode, string> = ({ children }) => {
+ const html = renderVDOM(children) // Convert VDOM to HTML
+ return `${html}`
+}
```
## Design Goals
@@ -1132,11 +1296,11 @@ export default layout
- Library agnostic. Strings are the interchange format.
- Pages are shallow apps. New page, new blank canvas.
- Just a program. `js` pages and layouts are just JavaScript programs. This provides an escape hatch to do anything. Use any template language want, but probably just use tagged template literals.
-- Steps remain orthogonal. Static file copying, css and js bundling, are mere optimizations on top of the `src` folder. The `src` folder should essentially run in the browser. Each step in a `top-bun` build should work independent of the others. This allows for maximal parallelism when building.
-- Standardized entrypoints. Every page in a `top-bun` site has a natural and obvious entrypoint. There is no magic redirection to learn about.
+- Steps remain orthogonal. Static file copying, css and js bundling, are mere optimizations on top of the `src` folder. The `src` folder should essentially run in the browser. Each step in a `domstack` build should work independent of the others. This allows for maximal parallelism when building.
+- Standardized entrypoints. Every page in a `domstack` site has a natural and obvious entrypoint. There is no magic redirection to learn about.
- Pages build into `index.html` files inside of named directories. This allows for naturally colocated assets next to the page, pretty URLs and full support for relative URLs.
- No parallel directory structures. You should never be forced to have two directories with identical layouts to put files next to each other. Everything should be colocatable.
-- Markdown entrypoints are named README.md. This allows for the `src` folder to be fully navigable in GitHub and other git repo hosting providing a natural hosted CMS UI.
+- Markdown entrypoints are named `page.md` or `README.md`. `README.md` allows for the `src` folder to be fully navigable in GitHub and other git repo hosting providing a natural hosted CMS UI. `page.md` is preferred when GitHub navigability is not a concern.
- Real TC39 ESM from the start.
- Garbage in, garbage out. Don't over-correct bad input.
- Conventions + standards. Vanilla file types. No new file extensions. No weird syntax to learn. Language tools should just work because you aren't doing anything weird or out of band.
@@ -1146,31 +1310,208 @@ export default layout
## FAQ
-Top-**Bun**? Like the JS runtime?
+Why DOMStack?
-: No, like the bakery from Wallace and Gromit in ["A Matter of Loaf and Death"](https://www.youtube.com/watch?v=zXBmZLmfQZ4s)
+: DOMStack is named after the DOM (Document Object Model) and the concept of stacking technologies together to build websites. It represents the layering of HTML, CSS, and JavaScript in a cohesive build system.
-How does `top-bun` relate to [`sitedown`](https://ghub.io/sitedown)
+How does `domstack` relate to [`sitedown`](https://ghub.io/sitedown)
-: `top-bun` used to be called `siteup` which is sort of like "markup", which is related to "markdown", which inspired the project `sitedown` to which `top-bun` is a spiritual off-shot of. Put a folder of web documents in your `top-bun` oven, and bake a website.
+: `domstack` used to be called `siteup` which is sort of like "markup", which is related to "markdown", which inspired the project `sitedown` to which `domstack` is a spiritual off-shoot of. Put a folder of web documents in your `domstack` build system, and generate a website.
## Examples
-Look at [examples](./examples/) and `top-bun` [dependents](https://github.com/bcomnes/top-bun/network/dependents) for some examples how `top-bun` can work.
+Look at [examples](./examples/) and `domstack` [dependents](https://github.com/bcomnes/domstack/network/dependents) for some examples how `domstack` can work.
## Implementation
-`top-bun` bundles the best tools for every technology in the stack:
+`domstack` bundles the best tools for every technology in the stack:
- `js` and `css` is bundled with [`esbuild`](https://github.com/evanw/esbuild).
- `md` is processed with [markdown-it](https://github.com/markdown-it/markdown-it).
- static files are processed with [cpx2](https://github.com/bcomnes/cpx2).
+- `ts` support via native typestripping in Node.js and esbuild.
+- `jsx/tsx` support via esbuild.
These tools are treated as implementation details, but they may be exposed more in the future. The idea is that they can be swapped out for better tools in the future if they don't make it.
+### Build Process Flow
+
+The following diagram illustrates the DomStack build process:
+
+```
+ βββββββββββββββ
+ β START β
+ ββββββββ¬βββββββ
+ β
+ βΌ
+ ββββββββββββββββββββ
+ β identifyPages() β
+ β β
+ β β’ Find pages β
+ β β’ Find layouts β
+ β β’ Find templates β
+ β β’ Find globals β
+ β β’ Find settings β
+ ββββββββββ¬ββββββββββ
+ β
+ β
+ βββββββββββββββββββββΌββββββββββββββββββββ
+ β β β
+ βΌ βΌ βΌ
+βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
+β buildEsbuild() β β buildStatic() β β buildCopy() β
+β β β β β β
+β β’ Bundle JS/CSS β β β’ Copy static β β β’ Copy extra β
+β β’ Generate β β files β β directories β
+β metafile β β (if enabled) β β from opts β
+ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ ββββββββββ¬βββββββββ
+ β β β
+ βββββββββββββββββββββΌββββββββββββββββββββ
+ β
+ βΌ
+ ββββββββββββββββββββ
+ β buildPages() β
+ β β
+ β β’ Process HTML β
+ β β’ Process MD β
+ β β’ Process JS β
+ β β’ Apply layouts β
+ ββββββββββ¬ββββββββββ
+ β
+ βΌ
+ ββββββββββββββββββββ
+ β Return Results β
+ β β
+ β β’ siteData β
+ β β’ esbuildResults β
+ β β’ staticResults β
+ β β’ copyResults β
+ β β’ pageResults β
+ β β’ warnings β
+ ββββββββββββββββββββ
+```
+
+The build process follows these key steps:
+
+1. **Page identification** - Scans the source directory to identify all pages, layouts, templates, and global assets
+2. **Destination preparation** - Ensures the destination directory is ready for the build output
+3. **Parallel asset processing** - Three operations run concurrently:
+ - JavaScript and CSS bundling via esbuild
+ - Static file copying (when enabled)
+ - Additional directory copying (from `--copy` options)
+4. **Page building** - Processes all pages, applying layouts and generating final HTML
+
+This architecture allows for efficient parallel processing of independent tasks while maintaining the correct build order dependencies.
+
+#### buildPages() Detail
+
+The `buildPages()` step processes pages in parallel with a concurrency limit:
+
+```
+ ββββββββββββββββββββ
+ β buildPages() β
+ ββββββββββ¬ββββββββββ
+ β
+ ββββββββββΌββββββββββ
+ β Resolve Once: β
+ β β’ Global vars β
+ β β’ All layouts β
+ ββββββββββ¬ββββββββββ
+ β
+ ββββββββββββββΌββββββββββββββββ
+ β Parallel Page Init β
+ β(Concurrency: min(CPUs, 24))β
+ ββββββββββββββ¬ββββββββββββββββ
+ β
+ ββββββββββββββββββββββΌβββββββββββββββββββββ
+ β β β
+ βΌ βΌ βΌ
+βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
+β MD Page Task β β HTML Page Task β β JS Page Task β
+βββββββββββββββββββ€ βββββββββββββββββββ€ βββββββββββββββββββ€
+β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β
+β β1. Parse MD β β β β1. Read .htmlβ β β β1. Import .jsβ β
+β β frontmatter β β β β file β β β β module β β
+β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β
+β βΌ β β βΌ β β βΌ β
+β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β
+β β2. Variable β β β β2. Variable β β β β2. Variable β β
+β β Resolution β β β β Resolution β β β β Resolution β β
+β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β β ββββββββ¬βββββββ β
+β βΌ β β βΌ β β βΌ β
+β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β
+β β builder + β β β βpage.vars.js β β β β Exported β β
+β β page.vars.jsβ β β β β β β β + page.varsβ β
+β βββββββββββββββ β β βββββββββββββββ β β βββββββββββββββ β
+βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
+ β β β
+ ββββββββββββββββββββββββΌβββββββββββββββββββββββ
+ β
+ βΌ
+ βββββββββββββββββββββββββ
+ β global.data.js runs β
+ β (receives PageData[])β
+ β stamps vars on pages β
+ βββββββββββββ¬ββββββββββββ
+ β
+ βΌ
+ βββββββββββββββββββββββββββββββββ
+ β Parallel Render + Write β
+ β (Concurrency: min(CPUs, 24)) β
+ βββββββββββββββββββββββββββββββββ
+```
+
+Variable Resolution Layers:
+- **Global vars** - Site-wide variables from `global.vars.js` (resolved once)
+- **Layout vars** - Layout-specific variables from layout functions (resolved once)
+- **Page-specific vars** vary by type:
+ - **MD pages**: page.vars.js + builder vars (from frontmatter)
+ - **HTML pages**: page.vars.js
+ - **JS pages**: exported vars β page.vars.js
+- **Global data** - Derived variables from `global.data.js`, stamped onto every page after all pages initialize (resolved once, after page init)
+
+### Watch Mode
+
+When you run `domstack --watch` (or `domstack -w`), domstack performs an initial build and then watches for changes, rebuilding only what's necessary. Watch mode uses two independent watch loops:
+
+**esbuild watch** β JS and CSS bundles are handled by esbuild's native `context.watch()`. In watch mode, output filenames are stable (no content hashes), so bundle changes never require a page HTML rebuild. Browser-sync detects the updated files on disk and reloads the browser directly.
+
+**chokidar watch** β Page files, layouts, templates, and config files are watched by chokidar. When a file changes, domstack determines the minimal set of pages to rebuild using dependency tracking maps built at startup.
+
+#### What triggers what
+
+| Change | Rebuild scope |
+|---|---|
+| `page.js`, `page.ts`, `page.html`, `page.md`, or `page.vars.*` | Only that page |
+| A file imported by a `page.js` or `page.vars.*` | Only the pages that import it (transitively) |
+| A layout file (`*.layout.js`) | Only the pages using that layout |
+| A file imported by a layout | Only the pages using the affected layout(s) |
+| A template file (`*.template.js`) | Only that template |
+| A file imported by a template | Only the affected template(s) |
+| `markdown-it.settings.*` | All `.md` pages |
+| `global.data.*` | All pages and templates |
+| `global.vars.*` or `esbuild.settings.*` | Full rebuild (esbuild restart + all pages) |
+| `client.js`, `style.css`, `*.layout.css`, `*.layout.client.*`, `global.client.*`, `global.css`, `*.worker.*` | esbuild handles it β no page rebuild |
+| Adding or removing an esbuild entry point (e.g. creating a new `client.js`) | esbuild restart + only the affected page(s) |
+| Adding or removing any other file | Full rebuild |
+
+#### Dependency tracking
+
+domstack uses [`@11ty/dependency-tree-typescript`](https://github.com/11ty/dependency-tree-typescript) to statically analyze ESM imports in page files, layout files, and template files. This means if your `page.js` imports a shared utility module, changing that module will only rebuild the pages that depend on it β not the entire site.
+
+esbuild tracks its own entry point dependencies independently. Changing a file imported by `client.js` will trigger an esbuild rebundle but will not trigger a page rebuild, since watch mode uses stable filenames.
+
+#### Stable filenames
+
+In watch mode, esbuild uses `[dir]/[name]` output patterns instead of `[dir]/[name]-[hash]`. This means the ``)
- : null}
- ${styles
- ? styles.map(style => html``)
- : null}
-
-
-
${vars.title}
+
+
${vars.authorImgUrl
- ? html`
`
+ ? html``
: null
}
${vars.authorName && vars.authorUrl
? html`
-
+
${vars.authorName}
`
: null
@@ -509,47 +599,45 @@ export default function blogLayout (layoutVars) {
${vars.publishDate
? html`
-
`
+ ? html``
: null
}
${vars.authorName && vars.authorUrl
? html`
-
+
${vars.authorName}
`
: null
@@ -509,47 +599,45 @@ export default function blogLayout (layoutVars) {
${vars.publishDate
? html`
- -
+ ${blogPosts.map(p => html`
+
- + + ${p.vars?.title} + + + `)} +
' + md.utils.escapeHtml(m[1]) + '
\n' + } else { + return '+ linkify: false, // Disable auto-linking + }) + + // Add only the plugins you want + newMd.use(myCustomPlugin) + + return newMd +} + +export default markdownItSettingsOverride +``` + +By default, DOMStack ships with the following markdown-it plugins enabled: + +- [markdown-it](https://github.com/markdown-it/markdown-it) +- [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote) +- [markdown-it-highlightjs](https://github.com/valeriangalliat/markdown-it-highlightjs) +- [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji) +- [markdown-it-sub](https://github.com/markdown-it/markdown-it-sub) +- [markdown-it-sup](https://github.com/markdown-it/markdown-it-sup) +- [markdown-it-deflist](https://github.com/markdown-it/markdown-it-deflist) +- [markdown-it-ins](https://github.com/markdown-it/markdown-it-ins) +- [markdown-it-mark](https://github.com/markdown-it/markdown-it-mark) +- [markdown-it-abbr](https://github.com/markdown-it/markdown-it-abbr) +- [markdown-it-task-lists](https://github.com/revin/markdown-it-task-lists) +- [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor) +- [markdown-it-attrs](https://github.com/arve0/markdown-it-attrs) +- [markdown-it-table-of-contents](https://github.com/cmaas/markdown-it-table-of-contents) + ## Variables -Pages, Layouts, and `postVars` all receive an object with the following parameters: +Pages and Layouts receive an object with the following parameters: -- `vars`: An object with the variables of `global.vars.js`, `page.vars.js`, and any front-matter,`vars` exports and `postVars` from the page merged together. -- `pages`: An array of [`PageData`](https://github.com/bcomnes/top-bun/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. +- `vars`: An object with the variables of `global.vars.ts`, `global.data.js`, `page.vars.ts`, and any front-matter or `vars` exports from the page merged together. +- `pages`: An array of [`PageData`](https://github.com/bcomnes/d omstack/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. - `page`: An object of the page being rendered with the following parameters: - `type`: The type of page (`md`, `html`, or `js`) - `path`: The directory path for the page. @@ -953,77 +1173,29 @@ Pages, Layouts, and `postVars` all receive an object with the following paramete Template files receive a similar set of variables: -- `vars`: An object with the variables of `global.vars.js` -- `pages`: An array of [`PageData`](https://github.com/bcomnes/top-bun/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. +- `vars`: An object with the variables of `global.vars.ts` +- `pages`: An array of [`PageData`](https://github.com/bcomnes/domstack/blob/master/lib/build-pages/page-data.js) instances for every page in the site build. Use this array to introspect pages to generate feeds and index pages. - `template`: An object of the template file data being rendered. -Where `T` is your set of variables in the `vars` object. - -### `postVars` post processing variables (Advanced) {#postVars} - -In `page.vars.js` files, you can export a `postVars` sync/async function that returns an object. This function receives the same variable set as pages and layouts. Whatever object is returned from the function is merged into the final `vars` object and is available in the page and layout. This is useful if you want to apply advanced rendering page introspection and insert it into a markdown document (for example, the last few blog posts on a markdown page.) - -For example: - -```js -// page.vars.js -import { html, render } from 'uhtml-isomorphic' - -export async function postVars ({ - pages -}) { - const blogPosts = pages - .filter(page => page.vars.layout === 'article') - .sort((a, b) => new Date(b.vars.publishDate) - new Date(a.vars.publishDate)) - .slice(0, 5) +### Derived global data (Advanced) - const blogpostsHtml = render(String, html`
-
- ${blogPosts.map(p => {
- const publishDate = p.vars.publishDate ? new Date(p.vars.publishDate) : null
- return html`
-
- - ${p.vars.title} - ${ - publishDate - ? html`` - : null - } - ` - })} -
Hello from TypeScript!
${vars.message}
` -} +This allows pages to return custom types (like VDOM or JSON) while ensuring layouts produce HTML strings: -export default page -``` - -#### Layout Function - -```typescript -// root.layout.ts -import type { LayoutFunction } from 'top-bun' -import { html, render } from 'uhtml-isomorphic' - -type Vars = { - siteName: string, - title?: string +```ts +// Define custom types +type VDOMNode = { + type: string + props: Record
- ${typeof children === 'string' ? html([children]) : children /* Support both uhtml and string children. Optional. */}
-
-
-