🥐 top-bun

npm version Actions Status Coverage Status Types in JS Neocities

top-bun: a traditional web bakery made with html, md, css and js.

(A bakery themed static site generator that’s as fun as making bread.)

npm install top-bun

Table of Contents

Usage

$ top-bun --help
Usage: top-bun [options]

    Example: top-bun --src website --dest public

    --src, -s             path to source directory (default: "src")
    --dest, -d            path to build destination directory (default: "public")
    --ignore, -i          comma separated gitignore style ignore string
    --drafts              Build draft pages with the `.draft.{md,js,html}` page suffix.
    --target, -t          comma separated target strings for esbuild
    --noEsbuildMeta       skip writing the esbuild metafile to disk
    --watch-only          watch and build the src directory without serving
    --help, -h            show help
    --version, -v         show version information
top-bun (v7.0.0)

top-bun builds a src directory into a dest directory (default: public). top-bun is also aliased to a tb bin.

top-bun is primarily a unix bin written for the Node.js runtime that is intended to be installed from npm as a devDependency inside a package.json committed to a git repository. It can be used outside of this context, but it works best within it.

Core Concepts

top-bun builds a website from “pages” in a src directory, nearly 1:1 into a dest directory. A src directory tree might look something like this:

src % tree
.
├── md-page
│        ├── README.md # directories with README.md in them turn into /md-page/index.html.
│        ├── client.js # Every page can define its own client.js script that loads only with it.
│        ├── style.css # Every page can define its own style.css style that loads only with it.
│        ├── loose-md-page.md # loose markdown get built in place, but lacks some page features.
│        └── nested-page # pages are built in place and can nest.
│               ├── README.md # This page is accessed at /md-page/nested-page/.
│               ├── client.js # nested pages are just pages, so they also can have a page scoped client and style.
│               └── style.css
├── html-page
│        ├── client.js
│        ├── page.html # Raw html pages are also supported. They support handlebars template blocks.
│        ├── page.vars.js # pages can define page variables in a page.vars.js.
│        └── style.css
├── feeds
│        └── feeds.template.js # Templates let you generate any file you want from variables and page data.
├── layouts # layouts can live anywhere. The inner content of your page is slotted into your layout.
│        ├── blog.layout.js # pages specify which layout they want by setting a `layout` page variable.
│        ├── blog.layout.css # layouts can define an additional layout style.
│        ├── blog.layout.client.js # layouts can also define a layout client.
│        ├── article.layout.js # layouts can extend other layouts, since they are just functions.
│        └── root.layout.js # the default layout is called root.
├── globals # global assets can live anywhere. Here they are in a folder called globals.
│        ├── global.client.js # you can define a global js client that loads on every page.
│        ├── global.css # you can define a global css file that loads on every page.
│        ├── global.vars.js # site wide variables get defined in global.vars.js.
│        └── esbuild.settings.js # You can even customize the build settings passed to esbuild!
├── README.md # This is just a top level page built from a README.md file.
├── client.js # the top level page can define a page scoped js client.
├── style.js # the top level page can define a page scoped Css style.
└── favicon-16x16.png # static assets can live anywhere. Anything other than JS, CSS and HTML get copied over automatically.

The core idea of top-bun is that a src directory of markdown, html and js “inner” documents will be transformed into layout wrapped html documents in the dest directory, along with page scoped js and css bundles, as well as a global stylesheet and global js bundle.

It ships with sane defaults so that you can point top-bun at a standard markdown documented repository and have it build a website with near-zero preparation.

Pages

Pages are a named directories inside of src, with one of the following page files inside of it.

Variables are available in all pages. md and html pages support variable access via handlebars template blocks. js pages receive variables as part of the argument passed to them. See the Variables section for more info.

A special variable called layout determines which layout the page is rendered into.

Because pages are just directories, they nest and structure naturally. Directories in the src folder that lack one of these special page files can exist along side page directories and can be used to store co-located code or static assets without conflict.

md pages

A md page looks like this:

src/page-name/README.md
# or
src/page-name/loose-md.md

An example of a md page:

---
title: A title for my markdown
favoriteBread: 'Baguette'
---

Just writing about baking.

## Favorite breads

My favorite bread is {{ vars.favoriteBread }}.

html pages

A html page looks like this:

src/page-name/page.html

An example html page:

<h2>Favorite breads</h2>
<ul>
  <li>French</li>
  <li>Sour dough</li>
  <li>Dutch crunch</li>
  <!-- favoriteBread defined in page.vars.js -->
  <li>{{ vars.favoriteBread }}</li>
</ul>

js pages

A js page looks like this:

src/page-name/page.js

An example js page:

export default async ({
  vars
}) => {
  return /* html */`<div>
    <p>This is just some html.</p>
    <p>My favorite cookie: ${vars.favoriteCookie}</p>
  </div>`
}

export const vars = {
  favoriteCookie: 'Chocolate Chip with Sea Salt'
}

It is it’s recommended to use some level of template processing over raw string templates so that html is well formed and you default escape variable values. Here is a more realistic js example that uses uhtml and types-in-js and top-bun page introspection.

// @ts-ignore
import { html } from 'uhtml-isomorphic'
import { dirname, basename } from 'node:path'

/**
 * @template T
 * @typedef {import('top-bun').LayoutFunction<T>} LayoutFunction
 */

/**
 * @type {LayoutFunction<{
 *   favoriteCake: string
 * }>}
 */
export default async function blogIndex ({
  vars: {
    favoriteCake
  },
  pages
}) {
  const yearPages = pages.filter(page => dirname(page.pageInfo.path) === 'blog')
  return html`<div>
    <p>I love ${favoriteCake}!!</p>
    <ul>
      ${yearPages.map(yearPage => html`<li><a href="${`/${yearPage.pageInfo.path}/`}">${basename(yearPage.pageInfo.path)}</a></li>`)}
    </ul>
  </div>`
}

export const vars = {
  favoriteCake: 'Chocolate Cloud Cake'
}

Page Styles

You can create a style.css file in any page folder. Page styles are loaded on just that one page. You can import common use styles into a style.css page style using css @import statements to re-use common css. You can @import paths to other css files, or out of npm modules you have installed in your projects node_modues folder. css page bundles are bundled using esbuild.

An example of a page style.css file:

/* /some-page/style.css */
@import "some-npm-module/style.css";
@import "../common-styles/button.css";

.some-page-class {
  color: blue;

  & .button {
    color: purple;
  }
}

Page JS Bundles

You can create a client.js file in any page folder. Page bundles are client side JS bundles that are loaded on that one page only. You can import common code and modules from relative paths, or npm modules. The client.js page bundles are bundle-split with every other client-side js entry-point, so importing common chunks of code are loaded in a maximally efficient way. Page bundles are run in a browser context only, however they can share carefully crafted code that also runs in a Node.js or layout context. js page bundles are bundled using esbuild.

An example of a page client.js file:

/* /some-page/client.js */
import { funnyLibrary } from 'funny-library'
import { someHelper } from '../helpers/foo.js'

await someHelper()
await funnyLibrary()

Page variable files

Each page can also have a page.vars.js file that exports a default function or object that contains page specific variables.

// export an object
export default {
  my: 'vars'
}

// OR export a default function
export default () => {
  return { my: 'vars' }
}

// OR export a default async function
export default async () => {
  return { my: 'vars' }
}

Page variable files have higher precedent than global.vars.js variables, but lower precedent than frontmatter or vars page exports.

Draft pages

If you add a .draft.{md,html,js} to any of the page types, the page is considered a draft page. Draft pages are not built by default. If you pass the --drafts flag when building or watching, the draft pages will be built. When draft pages are omitted, they are completely ignored.

Draft pages can be detected in layouts using the page.draft === true or pages[n].draft === true variable. It is a good idea to display something indicating the page is a draft in your templates so you don’t get confused when working with the --drafts flag.

Any static assets near draft pages will still be copied because static assets are processed in parallel from page generation (to keep things fast). If you have an idea on how to relate static assets to a draft page for omission, please open a discussion issue.

Layouts

Layouts are “outer page templates” that pages get rendered into. You can define as many as you want, and they can live anywhere in the src directory.

Layouts are named ${layout-name}.layout.js where ${layout-name} becomes the name of the layout. Layouts should have a unique name, and layouts with duplicate name will result in a build error.

Example layout file names:

src/layouts/root.layout.js # this layout is references as 'root'
src/other-layouts/article.layout.js # this layout is references as 'article'

At a minimum, your site requires a root layout (a file named root.layout.js), though top-bun ships a default root layout so defining one in your src directory is optional, though recommended.

All pages have a layout variable that defaults to root. If you set the layout variable to a different name, pages will build with a layout matching the name you set to that variable.

The following markdown page would be rendered using the article layout.

---
layout: 'article'
title: 'My Article Title'
---

Thanks for reading my article

A page referencing a layout name that doesn’t have a matching layout file will result in a build error.

The default root.layout.js

A layout is a js file that export default’s an async or sync function that implements an outer-wrapper html template that will house the inner content from the page (children) being rendered. Think of the bread in a sandwich. That’s a layout. 🥪

It is always passed a single object argument with the following entries:

The default root.layout.js is featured below, and is implemented with uhtml, though it could just be done with a template literal or any other template system.

root.layout.js can live anywhere in the src directory.

// @ts-ignore
import { html, render } from 'uhtml-isomorphic'

/**
 * @template T extends object
 * @typedef {import('top-bun').LayoutFunction<T>} LayoutFunction
 */

/**
 * Build all of the bundles using esbuild.
 *
 * @type {LayoutFunction<{
 *   title: string,
 *   siteName: string,
 *   defaultStyle: boolean
 * }>}
 */
export default function defaultRootLayout ({
  vars: {
    title,
    siteName = 'TopBun'
    /* defaultStyle = true  Set this to false in global or page vars to disable the default style in the default layout */
  },
  scripts,
  styles,
  children
  /* pages */
  /* page */
}) {
  return render(String, html`
    <!DOCTYPE html>
    <html>
    <head>
      <meta charset="utf-8">
      <title>${title ? `${title}` : ''}${title && siteName ? ' | ' : ''}${siteName}</title>
      <meta name="viewport" content="width=device-width, user-scalable=no" />
      ${scripts
        ? scripts.map(script => html`<script type='module' src="${script}"></script>`)
        : null}
      ${styles
        ? styles.map(style => html`<link rel="stylesheet" href=${style} />`)
        : null}
    </head>
    <body class="safe-area-inset">
      <main class="mine-layout">
        ${typeof children === 'string' ? html([children]) : children /* Support both uhtml and string children. Optional. */}
      </main>
    </body>
    </html>
`)
}

If your src folder doesn’t have a root.layout.js file somewhere in it, top-bun will use the default default.root.layout.js file it ships. The default root layout includes a special boolean variable called defaultStyle that lets you disable a default page style (provided by mine.css) that it ships with.

Nested layouts

Since layouts are just functions™️, they nest naturally. If you define the majority of your html page meta detritus in a root.layout.js, you can define additional layouts that act as child wrappers, without having to re-define everything in root.layout.js.

For example, you could define a blog.layout.js that re-uses the root.layout.js:

import defaultRootLayout from './root.layout.js'
// @ts-ignore
import { html } from 'uhtml-isomorphic'

/**
 * @template T extends object
 * @typedef {import('top-bun').LayoutFunction<T>} LayoutFunction
 */

/**
 * @typedef {import('./root.layout.js').SiteVars} SiteVars
 */

/** @type {LayoutFunction<SiteVars>} */
export default function blogLayout (layoutVars) {
  const { children: innerChildren, ...rest } = layoutVars
  const vars = layoutVars.vars

  const children = html`
    <article class="article-layout h-entry" itemscope itemtype="http://schema.org/NewsArticle">
      <header class="article-header">
        <h1 class="p-name article-title" itemprop="headline">${vars.title}</h1>
        <div class="metadata">
          <address class="author-info" itemprop="author" itemscope itemtype="http://schema.org/Person">
            ${vars.authorImgUrl
              ? html`<img height="40" width="40"  src="${vars.authorImgUrl}" alt="${vars.authorImgAlt}" class="u-photo" itemprop="image">`
              : null
            }
            ${vars.authorName && vars.authorUrl
              ? html`
                  <a href="${vars.authorUrl}" class="p-author h-card" itemprop="url">
                    <span itemprop="name">${vars.authorName}</span>
                  </a>`
              : null
            }
          </address>
          ${vars.publishDate
            ? html`
              <time class="dt-published" itemprop="datePublished" datetime="${vars.publishDate}">
                <a href="#" class="u-url">
                  ${(new Date(vars.publishDate)).toLocaleString()}
                </a>
              </time>`
            : null
          }
          ${vars.updatedDate
            ? html`<time class="dt-updated" itemprop="dateModified" datetime="${vars.updatedDate}">Updated ${(new Date(vars.updatedDate)).toLocaleString()}</time>`
            : null
          }
        </div>
      </header>

      <section class="e-content" itemprop="articleBody">
        ${typeof innerChildren === 'string'
          ? html([innerChildren])
          : innerChildren /* Support both uhtml and string children. Optional. */
        }
      </section>

      <!--
        <footer>
            <p>Footer notes or related info here...</p>
        </footer>
      -->
    </article>
  `

  const rootArgs = { ...rest, children }
  return defaultRootLayout(rootArgs)
}

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.

Layout styles

You can create a ${layout-name}.layout.css next to any layout file.

/* /layouts/article.layout.css */
.layout-specific-class {
  color: blue;

  & .button {
    color: purple;
  }
}

/* This layout style is included in every page rendered with the 'article' layout */

Layout styles are loaded on all pages that use that layout. Layout styles are bundled with esbuild and can bundle relative and npm css using css @import statements.

Layout JS Bundles

You can create a ${layout-name}.layout.client.js next to any layout file.

/* /layouts/article.layout.client.js */

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 and can bundle relative and npm modules using ESM import statements.

Nested layout 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:

/* article.layout.css  */
@import "./root.layout.css";

This will include the layout style from the root layout in the article layout style.

/* article.layout.client.js  */
import './root.layout.client.js'

These imports will include the root.layout.js layout assets into the blog.layout.js 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.

Templates

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 object, or inject any other kind of data fetched at build time. Template files can be located anywhere and look like:

name-of-template.txt.template.js

${name-portion}.template.js

Template files are a 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.

/**
 * @template T
 * @typedef {import('top-bun').TemplateFunction<T>} TemplateFunction
 */

/**
 * @type {TemplateFunction<{
 * foo: string,
 * testVar: string
 * }>}
 */
export default async ({
  vars: {
    foo
  }
}) => {
  return `{Hello world

This is just a file with access to global vars: ${foo}
`
}

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.

/**
 * @template T
 * @typedef {import('top-bun').TemplateFunction<T>} TemplateFunction
 */

/**
 * @type {TemplateFunction<{
 * foo: string,
 * }>}
 */
export default async ({
  vars: { foo }
}) => ({
  content: `Hello world

This is just a file with access to global vars: ${foo}`,
  outputName: './single-object-override.txt'
})

Object array template

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.

/**
 * @template T
 * @typedef {import('top-bun').TemplateFunction<T>} TemplateFunction
 */

/**
 * @type {TemplateFunction<{
 * foo: string,
 * testVar: string
 * }>}
 */
export default async function objectArrayTemplate ({
  vars: {
    foo,
    testVar
  }
}) {
  return [
    {
      content: `Hello world

This is just a file with access to global vars: ${foo}`,
      outputName: 'object-array-1.txt'
    },
    {
      content: `Hello world again

This is just a file with access to global vars: ${testVar}`,
      outputName: 'object-array-2.txt'
    }
  ]
}

AsyncIterator template

An AsyncIterator that yields objects with content and outputName entries.

/**
 * @template T
 * @typedef {import('top-bun').TemplateAsyncIterator<T>} TemplateAsyncIterator
 */

/** @type {TemplateAsyncIterator<{
 * foo: string,
 * testVar: string
 * }>} */
export default async function * ({
  vars: {
    foo,
    testVar
  }
}) {
  // First item
  yield {
    content: `Hello world

This is just a file with access to global vars: ${foo}`,
    outputName: 'async-iterator-1.txt'
  }

  // Second item
  yield {
    content: `Hello world again

This is just a file with access to global vars: ${testVar}`,
    outputName: 'async-iterator-2.txt'
  }
}

RSS Feed Template Example

Templates receive the standard variables available to pages, so its possible to perform page introspection and generate RSS feeds of website content.

The following example shows how to generate an RSS and JSON feed of the last 10 date sorted pages with the blog layout using the AsyncIterator template type.

import pMap from 'p-map'
// @ts-ignore
import jsonfeedToAtom from 'jsonfeed-to-atom'

/**
 * @template T
 * @typedef {import('top-bun').TemplateAsyncIterator<T>} 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 ({
  vars: {
    siteName,
    homePageUrl,
    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)

  const jsonFeed = {
    version: 'https://jsonfeed.org/version/1',
    title: siteName,
    home_page_url: homePageUrl,
    feed_url: `${homePageUrl}/feed.json`,
    description: siteDescription,
    author: {
      name: authorName,
      url: authorUrl,
      avatar: authorImgUrl
    },
    items: await pMap(blogPosts, async (page) => {
      return {
        date_published: page.vars['publishDate'],
        title: page.vars['title'],
        url: `${homePageUrl}/${page.pageInfo.path}/`,
        id: `${homePageUrl}/${page.pageInfo.path}/#${page.vars['publishDate']}`,
        content_html: await page.renderInnerPage({ pages })
      }
    }, { concurrency: 4 })
  }

  yield {
    content: JSON.stringify(jsonFeed, null, '  '),
    outputName: './feeds/feed.json'
  }

  yield {
    content: jsonfeedToAtom(jsonFeed),
    outputName: './feeds/feed.xml'
  }
}

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.

global.vars.js

The 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.

export default {
  siteName: 'The name of my website',
  authorName: 'Mr. Wallace'
}

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.

export const browser = {
  'process.env.TRANSPORT': transport,
  'process.env.HOST': host
}

The exported object is passed to esbuild’s define options and is available to every js bundle.

global.client.js

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.

console.log('I run on every page in the site!')

global.css

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

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. Use this to customize the esbuild settings directly. You can break top-bun with this, so be careful. Here is an example of using this file to polyfill node builtins in the browser bundle:

import { polyfillNode } from 'esbuild-plugin-polyfill-node'

export default async function esbuildSettingsOverride (esbuildSettings) {
  esbuildSettings.plugins = [
    polyfillNode(),
  ]
  return esbuildSettings
}

Variables

Pages, Layouts, and postVars all receive an object with the following parameters:

Template files receive a similar set of variables:

Variable types

The following types are exported from top-bun:

LayoutFunction<T>
PostVarsFunction<T>
PageFunction<T>
TemplateFunction<T>
TemplateAsyncIterator<T>

Where T is your set of variables in the vars object.

postVars post processing variables (Advanced)

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:

// 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)

  const blogpostsHtml = render(String, html`<ul class="blog-index-list">
      ${blogPosts.map(p => {
        const publishDate = p.vars.publishDate ? new Date(p.vars.publishDate) : null
        return html`
          <li class="blog-entry h-entry">
            <a class="blog-entry-link u-url u-uid p-name" href="/${p.pageInfo.path}/">${p.vars.title}</a>
            ${
              publishDate
                ? html`<time class="blog-entry-date dt-published" datetime="${publishDate.toISOString()}">
                    ${publishDate.toISOString().split('T')[0]}
                  </time>`
                : null
            }
          </li>`
        })}
    </ul>`)

  const pageVars = {
    blogPostsHtml: blogpostsHtml
  }

  return pageVars
}

This postVars renders some html from page introspection of the last 5 blog post titles. In the associated page markdown, this variable is available via a handlebars placeholder.

<!-- README.md -->
## [Blog](./blog/)

{{{ vars.blogPostsHtml }}}

Design Goals

FAQ

Top-Bun? Like the JS runtime?
No, like the bakery from Wallace and Gromit in “A Matter of Loaf and Death”
How does top-bun relate to 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.

Examples

Look at examples and top-bun dependents for some examples how top-bun can work.

Implementation

top-bun bundles the best tools for every technology in the stack:

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.

Roadmap

top-bun works and has a rudimentary watch command, but hasn’t been battle tested yet. If you end up trying it out, please open any issues or ideas that you have, and feel free to share what you build.

Some notable features are included below, see the roadmap for a more in depth view of whats planned.

History

License

MIT