π₯ top-bun
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
- π
top-bun
docs website - π’ v7 Announcement
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.
- Running
top-bun
will result in abuild
by default. - Running
top-bun --watch
will build the site and start an auto-reloading development web-server that watches for changes.
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.
βββ 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.
md
pages are CommonMark markdown pages, with an optional YAML front-matter block.html
pages are an inner html fragment that get inserted into the page layout.js
pages are a js file that exports a default function that resolves into an inner-html fragment that is inserted into the page layout.
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
md
pages have two types: aREADME.md
in a folder, or a loosewhatever-name-you-want.md
file.README.md
files transform to anindex.html
at the same path, andwhatever-name-you-want.md
loose markdown files transform intowhatever-name-you-want.html
files at the same path in thedest
directory.md
pages can have YAML frontmatter, with variables that are accessible to the page layout and handlebars template blocks when building.- You can include html in markdown files, so long as you adhere to the allowable markdown syntax around html tags.
md
pages support handlebars template placeholders.- You can disable
md
page handlebars processing by setting thehandlebars
variable tofalse
. md
pages support many github flavored markdown features.
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
html
pages are namedpage.html
inside an associated page folder.html
pages are the simplest page type intop-bun
. They let you build with raw html for when you donβt want that page to have access to markdown features. Some pages are better off with just rawhtml
.html
page variables can only be set in apage.vars.js
file inside the page directory.html
pages support handlebars template placeholders.- You can disable
html
page handlebars processing by setting thehandlebars
variable tofalse
.
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
js
pages consist of a named directory with apage.js
inside of it, that exports a default function that returns the contents of the inner page.- a
js
page needs toexport default
a function (async or sync) that accepts a variables argument and returns a string of the inner html of the page, or any other type that your layout can accept. - A
js
page can export avars
object or function (async or sync) that takes highest variable precedence when rendering the page.export vars
is similar to amd
pageβs front matter. - A
js
page receives the standardtop-bun
Variables set. - There is no built in handlebars support in
js
pages, however you are free to use any template library that you can import. js
pages are run in a Node.js context only.
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:
vars
: An object of global, page folder, and page variables merged together. Pages can customize layouts by providing or overriding global defaults.scripts
: array of paths that should be included onto the page in a script tag src with typemodule
.styles
: array of paths that should be included onto the page in alink rel="stylesheet"
tag with thehref
pointing to the paths in the array.children
: A string of the inner content of the page, or whatever type your js page functions returns.md
andhtml
page types always return strings.pages
: An array of page data that you can use to generate index pages with, or any other page-introspection based content that you desire.page
: An object with metadata and other facts about the current page being rendered into the template. This will also be found somewhere in thepages
array.
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.
Variables
Pages, Layouts, and postVars
all receive an object with the following parameters:
vars
: An object with the variables ofglobal.vars.js
,page.vars.js
, and any front-matter,vars
exports andpostVars
from the page merged together.pages
: An array ofPageData
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
, orjs
)path
: The directory path for the page.outputName
: The output name of the final file.outputRelname
: The relative output name/path of the output file.pageFile
: Rawsrc
path details of the page filepageStyle
: file info if the page has a page styleclientBundle
: file info if the page has a page js bundlepageVars
: file info if the page has a page vars
Template files receive a similar set of variables:
vars
: An object with the variables ofglobal.vars.js
pages
: An array ofPageData
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.
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
- Convention over configuration. All configuration should be optional, and at most it should be minimal.
- Align with the
index.html
/README.md
pattern. - The HTML is the source of truth.
- Donβt re-implement what the browser already provides!
- No magic
<link>
or<a>
tag magic. - Donβt facilitate client side routing. The browser supports routing by default.s
- Accept the nature of the medium. Browsers browse html documents. Donβt facilitate shared state between pages.
- No magic
- 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. Thesrc
folder should essentially run in the browser. Each step in atop-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. - 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. - 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.
- Encourage directly runnable source files. Direct run is an incredible, undervalued feature more people should learn to use.
- Support typescript, via ts-in-js and type stripping features when available.
- Embrace the now. Limit support to pretend you are working in the future (technology predictions nearly always are wrong!)
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 tositedown
top-bun
used to be calledsiteup
which is sort of like βmarkupβ, which is related to βmarkdownβ, which inspired the projectsitedown
to whichtop-bun
is a spiritual off-shot of. Put a folder of web documents in yourtop-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:
js
andcss
is bundled withesbuild
.md
is processed with markdown-it.- static files are processed with cpx2.
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.
-
md
pages -
js
pages -
html
pages -
client.js
page bundles -
style.css
page stylesheets -
page.vars.js
page variables -
loose-markdown-pages.md
- Static asset copying.
- CLI build command
- CLI watch command
- Ignore globbing
- Nested site dest (
src
=.
,dest
=public
) - Default layouts/styles with 0 config starting point
- More examples and ideas.
- Hardened error handling w/ tests
- Multiple layout files
- Nested layout files
- Layout styles
- Layout scripts
- Template files
- Page data available to pages, layouts and template files.
- Handlebars template support in
md
andhtml
-
mjs
andcjs
file extension support - Improved watch log output
- Docs website built with
top-bin
: https://top-bun.org -
--eject
cli flag - Global assets can live anywhere
- Built in browsersync dev server
- Real default layout style builds
- β¦See roadmap