A composable, incremental, turnkey document compiler
\n\n
\n \n
\n\n> Read the blog post: [AM010 - Hot Stuff](https://abstractmachines.dev/posts/am010-hot-stuff.html)\n\nhotstuff is **turnkey** — it makes almost no assumptions about how\nyou structure or write your content. There's also no plugins whatsoever.\n\nhotstuff is **composable** — touch a few files in your existing folder\nstructure and it'll just work. Near zero-cost, and your content is always fully\nportable.\n\nhotstuff is **incremental** —- it aggressively caches your project so you\ncan use it on hundreds of thousands of files.\n\nJust one command away:\n\n* *Cargo*: `cargo install github.com/AbstractMachinesLab/hotstuff`\n* *Yarn*: `yarn global add @abstractmachines/hotstuff`\n* *NPM*: `npm install --global @abstractmachines/hotstuff`\n\n## Getting Started\n\nIf you put a `hotstuff-project` file on the root of your project, hotstuff will\nlook throughout your whole project for `site` files.\n\n`site` files tell `hotstuff` that this particular folder should be compiled\ninto a website.\n\nSo if you have your posts in the following structure:\n\n```sh\nmy/website Ī» tree\n.\nāāā pages\nāĀ Ā āāā First-post.md\nāĀ Ā āāā Some-other-post.md\nāāā sections\n āāā about.md\n āāā hire-me.md\n āāā projects.md\n```\n\nYou just need to `touch` a few files:\n\n```sh\nmy/website Ī» touch hotstuff-project\nmy/website Ī» touch pages/site sections/site\n```\n\nAnd you can run `hotstuff serve` to compile the website using the same tree\nstructure under a `_public` folder, and serve it with hot-reloading.\n\n```sh\nmy/website Ī» hotstuff serve\n11:19:09 INFO :: Building project...\n11:19:09 INFO :: Built 9 artifacts in 6ms\n11:19:09 INFO :: Done in 7ms\n11:19:09 INFO :: Server listening on http://0.0.0.0:4000\n```\n\nNow your file structure looks like:\n\n```sh\nmy/website Ī» tree\n.\nāāā _public\nāĀ Ā āāā pages\nāĀ Ā āĀ Ā āāā First-post.html\nāĀ Ā āĀ Ā āāā Some-other-post.html\nāĀ Ā āāā sections\nāĀ Ā āāā about.html\nāĀ Ā āāā hire-me.html\nāĀ Ā āāā projects.html\nāāā hotstuff-project\nāāā pages\nāĀ Ā āāā First-post.md\nāĀ Ā āāā Some-other-post.md\nāĀ Ā āāā site\nāāā sections\n āāā about.md\n āāā hire-me.md\n āāā projects.md\n āāā site\n```\n\nNote that the `_public` folder is ready for you to serve however you feel like.\nUpload to S3, Now, GCS, Github pages, or wherever really.\n\n## Installation\n\n### NPM\n\nIf you're already running `npm` or `yarn`, you can just run `yarn global add\n@abstractmachines/hotstuff` or `npm install -g @abstractmachines/hotstuff` to\nget the right binary in your computer.\n\nIf you're running against the Github package registry, our scoped name is\n`@abstractmachineslab` instead.\n\n### Source \n\nYou can install it locally via source if you have a running Rust toolchain with:\n\n```sh\ncurl https://codeload.github.com/AbstractMachinesLab/hotstuff/tar.gz/main > hotstuff.tar.gz\ntar xzf main.tar.gz\ncd hotstuff\nmake install\n```\n\nThen `hotstuff` should be available globally.\n\n## Features\n\n### Incremental Builds\n\nRunning `hotstuff build` will plan a build of your entire site every time, but\nit will only execute the bits required to get you to your end state.\n\nThere is no in-memory build state, and instead build plan diffing is implemented\non top of the artifacts that are produced.\n\nYou can always call `hotstuff build --force` to skip the diffing and redo al\nthe work.\n\n### Local Server\n\nYou can run `hotstuff serve` to start up a static file server with incremental\ncompilation and hot-reloading.\n\nThere's no in-memory build state, and the build diffs are recomputed in the\nbackground for you. So you get a re-build within a few milliseconds of changing\na file, and the browser will only reload the assets that changed.\n\nIt doesn't get anymore turnkey than this.\n\n### Templating\n\nYou'll quickly notice that the bare compilation from Markdown to HTML doesn't\nquite fit all use-cases. To alleviate this `hotstuff` lets you specify in your\n`site` file a template file to be used for all the Markdown files within that\nspecific site.\n\nSay you wanted to wrap all of the pages from the example above in a common\nmarkup: add a `` to all of them. You'd write a template\nfile:\n\n```html\n\n \n \n \n \n {| document |}\n \n\n```\n\nAnd in your `site` file you'd point to it:\n\n```lisp\n(template \"path/to/template.html\")\n```\n\nVoila! That's all it takes to get the templating up and running.\n\n### Assets\n\nTo copy assets (any supporting file to your site) you can use the `(assets\n...)` rule:\n\n```lisp\n(assets\n style.css\n logo.svg\n bg_music.midi)\n```\n\nAnd they will be automatically copied from their location, relative to the\n`site` file.\n\nYou can also use the shorthand `.` instead of listing your assets to have all\nthe files in the folder copied over. This is not recursive.\n\n## Credits\n\nhotstuff is inspired by prior art:\n\n* the `cactus` static site generator\n* the `dune` build system, with its composability\n* the `bazel` build system, with its aggressive incremental compilation\n techniques\n\nIf you'd like to support this project consider doing so on Patreon:\n\n\n\n\n","readmeFilename":"README.md"}
![\"Travis](\"https://img.shields.io/travis/AbstractMachinesLab/hotstuff?style=flat-square\")
\n![\"Become](\"https://c5.patreon.com/external/logo/become_a_patron_button.png\"){kind=logo}
\n\n","readmeFilename":"README.md"}