A composable, turnkey document compiler
npm install @abstractmachines/hotstuffA composable, incremental, turnkey document compiler
> Read the blog post: AM010 - Hot Stuff
hotstuff is turnkey — it makes almost no assumptions about how
you structure or write your content. There's also no plugins whatsoever.
hotstuff is composable — touch a few files in your existing folder
structure and it'll just work. Near zero-cost, and your content is always fully
portable.
hotstuff is incremental —- it aggressively caches your project so you
can use it on hundreds of thousands of files.
Just one command away:
Cargo*: cargo install github.com/AbstractMachinesLab/hotstuff
Yarn*: yarn global add @abstractmachines/hotstuff
NPM*: npm install --global @abstractmachines/hotstuff
If you put a hotstuff-project file on the root of your project, hotstuff will
look throughout your whole project for site files.
site files tell hotstuff that this particular folder should be compiled
into a website.
So if you have your posts in the following structure:
``sh`
my/website Ī» tree
.
āāā pages
āĀ Ā āāā First-post.md
āĀ Ā āāā Some-other-post.md
āāā sections
āāā about.md
āāā hire-me.md
āāā projects.md
You just need to touch a few files:
`sh`
my/website Ī» touch hotstuff-project
my/website Ī» touch pages/site sections/site
And you can run hotstuff serve to compile the website using the same tree_public
structure under a folder, and serve it with hot-reloading.
`sh`
my/website Ī» hotstuff serve
11:19:09 INFO :: Building project...
11:19:09 INFO :: Built 9 artifacts in 6ms
11:19:09 INFO :: Done in 7ms
11:19:09 INFO :: Server listening on http://0.0.0.0:4000
Now your file structure looks like:
`sh`
my/website Ī» tree
.
āāā _public
āĀ Ā āāā pages
āĀ Ā āĀ Ā āāā First-post.html
āĀ Ā āĀ Ā āāā Some-other-post.html
āĀ Ā āāā sections
āĀ Ā āāā about.html
āĀ Ā āāā hire-me.html
āĀ Ā āāā projects.html
āāā hotstuff-project
āāā pages
āĀ Ā āāā First-post.md
āĀ Ā āāā Some-other-post.md
āĀ Ā āāā site
āāā sections
āāā about.md
āāā hire-me.md
āāā projects.md
āāā site
Note that the _public folder is ready for you to serve however you feel like.
Upload to S3, Now, GCS, Github pages, or wherever really.
If you're already running npm or yarn, you can just run yarn global add
@abstractmachines/hotstuff or npm install -g @abstractmachines/hotstuff to
get the right binary in your computer.
If you're running against the Github package registry, our scoped name is
@abstractmachineslab instead.
You can install it locally via source if you have a running Rust toolchain with:
`sh`
curl https://codeload.github.com/AbstractMachinesLab/hotstuff/tar.gz/main > hotstuff.tar.gz
tar xzf main.tar.gz
cd hotstuff
make install
Then hotstuff should be available globally.
Running hotstuff build will plan a build of your entire site every time, but
it will only execute the bits required to get you to your end state.
There is no in-memory build state, and instead build plan diffing is implemented
on top of the artifacts that are produced.
You can always call hotstuff build --force to skip the diffing and redo al
the work.
You can run hotstuff serve to start up a static file server with incremental
compilation and hot-reloading.
There's no in-memory build state, and the build diffs are recomputed in the
background for you. So you get a re-build within a few milliseconds of changing
a file, and the browser will only reload the assets that changed.
It doesn't get anymore turnkey than this.
You'll quickly notice that the bare compilation from Markdown to HTML doesn't
quite fit all use-cases. To alleviate this hotstuff lets you specify in yoursite file a template file to be used for all the Markdown files within that
specific site.
Say you wanted to wrap all of the pages from the example above in a common
markup: add a to all of them. You'd write a template
file:
`html`
{| document |}
And in your site file you'd point to it:
`lisp`
(template "path/to/template.html")
Voila! That's all it takes to get the templating up and running.
To copy assets (any supporting file to your site) you can use the (assets
...) rule:
`lisp`
(assets
style.css
logo.svg
bg_music.midi)
And they will be automatically copied from their location, relative to the
site file.
You can also use the shorthand . instead of listing your assets to have all
the files in the folder copied over. This is not recursive.
hotstuff is inspired by prior art:
* the cactus static site generatordune
* the build system, with its composabilitybazel` build system, with its aggressive incremental compilation
* the
techniques
If you'd like to support this project consider doing so on Patreon: