https://github.com/anthonyec/staticbuild
🙅🏻♀️ A static site generator that isn't for you!
https://github.com/anthonyec/staticbuild
Last synced: 2 months ago
JSON representation
🙅🏻♀️ A static site generator that isn't for you!
- Host: GitHub
- URL: https://github.com/anthonyec/staticbuild
- Owner: anthonyec
- Created: 2022-04-24T18:20:42.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2026-03-26T21:12:35.000Z (2 months ago)
- Last Synced: 2026-03-27T08:48:31.723Z (2 months ago)
- Language: TypeScript
- Homepage:
- Size: 2.29 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# staticbuild
A static site generator that isn't for you!
`staticbuild` is a fast static file website generator with minimum support for anything other than my own stuff.
I'm currently using this on the following projects:
- [anthonyec/website](https://github.com/anthonyec/website)
- [anthonyec/gnorman](https://github.com/anthonyec/gnorman)
- [anthonyec/archive](https://github.com/anthonyec/archive)
## Features
- Fast and lightweight
- No need for configuration
- Good and nice asset handling
- Automatic page reloading
- Enjoyable to use, with fun features like [buildtime](#sbbuildtime) scripting
## Why
Many years ago I was using `jekyll` for generating [my website](https://anthonycossins.com/). But after switching to a new computer, I found it a pain in the butt to setup all the junk that was required to get my site running.
Out of frustration I built my own static site generator which is faster, simpler and makes me feel good.
## Usage
### Building a site
```sh
staticbuild [--watch, --dry-run, --check]
```
### Viewing the site
There isn't a built-in way to serve the website generated by `staticbuild`. I like using [`http-server`](https://www.npmjs.com/package/http-server) as the server.
```sh
npx http-server -c-1 ./dist -p 8081
```
## Documentation
### Special HTML Tags
#### ``
Use this tag to inline external HTML partials into a document.
```html
```
It's works like Mustache partials except you can place the partials files anywhere, and custom attributes can be passed
into the template.
```html
```
Custom attributes can be found on the `attributes` object.
```html
{{attributes.title}}
```
Children a `` tag can also be passed into a partial.
```html
Option 1
Option 2
Option 3
```
And then accessed with `attributes.children`.
```html
{{{attributes.children}}}
```
Since all Mustache variables by default are strings, use triple brackets `{{{ }}}` to output HTML unescaped. This lets `staticbuild` to continue to parse the children as HTML.
Note that any script or style tags are not magically scoped to a file. So make sure it is accounted for in code.
```html
Click me!
// A `querySelectorAll` is used instead of `querySelector` since there could
// be multiple buttons included on a page.
const buttons = document.querySelectorAll("button")
for (const button of buttons) {
button.addEventListener("click", () => console.log("HELLO"))
}
```
### Special HTML Attributes
#### `sb:inline`
SVG images can be inlined into the document. This keeps the HTML template clean while giving access to the SVG elements to style with CSS or modify with JS.
```html
```
#### `sb:selector`
Use this to conditionally show elements based on the existence of other elements in the DOM.
This is useful if content is dynamic but uses a shared layout. For example, conditionally loading a video player script if a collection entry contains a ``.
```html
{{#collection.blog}}
{{{content}}}
{{/collection.blog}}
```
#### `sb:ignore`
This tag can be used on any HTML attribute to have `staticbuild` processing it.
I don't like this, but I currently use it skip `<h1>` tags on certain pages being used as a title.
```html
<title>Actual page title</title>
<h1 sb:ignore>Visual title</h1>
```
#### `sb:buildtime`
Arbitrary JavaScript can be executed at build time! You heard that correct.
Since the Mustache template language is logic-less, this attribute provides the full power of a scripting language in a template.
The following script will get executed when the HTML page is parsed. The final rendered HTML will not contain the script.
```html
<script sb:buildtime>
// "Hello!" will appear in the CLI instead of the browser.
console.log("Hello!")
```
By default, script execution happens after templating, markdown rendering and extracting assets from the HTML.
DOM API access is limited because execution happens within the Node.js process. However, simple access to the DOM tree is provided via `node-html-parser`.
```html
// A `<span>` element will be added to the document at build time.
const body = document.querySelector("body")
body.append("<span>Hello!</span>")
```
Data can be provided to the current HTML template using the `sb:buildtime` attribute on a `` element.
Provide data needs to a valid JSON object.
```html
{ "items": ["1", "2", "3"] }
```
Once defined, the data can then be accessed using Mustache in the same HTML page under the `page.data` field.
```html
- List item number: {{.}}
{{#page.data.items}}
{{/page.data.items}}
- List item number: 1
- List item number: 2
- List item number: 3
```
Build time data will be parsed before any parsing of the HTML page has happened.
## Tests
There are snapshot tests that take files as input and check that running `staticbuild` produced the expected output.
Each test case is a subdirectory in `./tests`. Running the test command will run all the test cases.
```sh
npm t
```
To run a specific test case, use the `--spec` argument and the name of a test case subdirectory.
```sh
npm t -- --spec basic_includes
```
When creating or modifying tests, you can update the expected snapshot automatically using the `--update` argument. This will save the output as the expected. Make sure the output is what you actually expect!
```sh
npm t -- -u # This is the shortname for `update`.
```
This can be used in combination with the `--spec` argument. The following command updates the expected output for one spec.
```sh
npm t -- --spec basic_includes -u
```
To skip a test case, name a subdirectory with a "x\_" prefix. For example, "x_basic_page" will skip the "basic_page" test.
## AI Usage
AI training be gone! I do not give you permission to train on this codebase.