Overview

HastySite is a minimalist but powerful static site generator written in Nim which aims to be fast at processing content and highly configurable to suit your own needs.

Key Features

  • Built-in rich markdown support via HastyScribe.
  • Built-in mustache support for page templates.
  • Limited support for standard CSS variables.
  • Fully configurable content and asset processing pipeline, using the min programming language.
  • Custom script definition, using the min programming language.
  • Default stylesheet and fonts from HastyScribe.
  • Default scripts and rules to get started quickly.
  • All packed in a single executable file, with no dependencies, available for the most common desktop platforms.

Why HastySite?

HastySite is a static-site generator, similar to hundreds of others. Why bother with yet another one then?

Because HastySite:

Technology and Credits

HastySite has been built leveraging the following open source projects:

Special thanks also to the creators and maintainers of the following projects, that made HastySite possible:

Sites Using HastySite

HastySite powers the following web sites:

Getting Started

Download

You can download one of the following pre-built HastySite binaries:

Building from Source

Alternatively, you can build HastySite from source as follows:

  1. Download and install nim.
  2. Download and build Nifty, and put the nifty executable somewhere in your $PATH.
  3. Clone the HastySite repository.
  4. Navigate to the HastySite repository local folder.
  5. Run the following command to download HastySite’s dependencies.

    nifty install

  6. Run the following command to compile HastySite:

    nim c -d:release hastysite.nim

Tip

You should put the compiled HastySite executable somewhere in yout $PATH.

Running HastySite

To create a new site, run the following command in an empty directory:

hastysite init

This will create the following default directory structure:

Tip

Default folder paths can be configured in your settings.json file.

Then, create your first page by running the following command and specifying the page ID and Title:

hastysite page ID: home Title: Home Page ----- id: home title: "Home Page" content-type: page ----- Create page? [yes/no]: y

Finally, run the following command to generate your site contents (just an empty home page for now) and copy the default assets.

hastysite build Preprocessing... Processing rules... - Writing file: output/index.html - Copying: assets/fonts/SourceSansPro-Regular.woff -> output/fonts/SourceSansPro-Regular.woff - Copying: assets/fonts/SourceSansPro-It.woff -> output/fonts/SourceSansPro-It.woff - Copying: assets/fonts/fontawesome-webfont.woff -> output/fonts/fontawesome-webfont.woff - Copying: assets/fonts/SourceCodePro-Regular.woff -> output/fonts/SourceCodePro-Regular.woff - Copying: assets/fonts/SourceSansPro-Bold.woff -> output/fonts/SourceSansPro-Bold.woff - Copying: assets/fonts/SourceSansPro-BoldIt.woff -> output/fonts/SourceSansPro-BoldIt.woff - Writing file: output/styles/hastysite.css - Writing file: output/styles/site.css - Writing file: output/styles/luxbar.css - Writing file: output/styles/hastyscribe.css - Writing file: output/styles/fonts.css Postprocessing... All done.

That’s it! You can view the result by serving the output directory from any web server.

Usage

HastySite is a simple command-line program that supports some default commands and options, described in the following sections.

Syntax

hastysite command [ options ]

Default Commands

The following sections define the default commands provided by HastySite. All of them except for init can be modified, and you can also configure your own commands by creating your own min scripts and placing them in the scripts directory.

build

Builds the site by preprocessing contents and assets, processing rules defined in the rules.min file, and creating a temporary file containing the checksums of all newly-generated files. By doing so, the next time this command is executed, only the files that have actually been modified will be copied to the output directory.

The rules.min file processed by this command:

Note

This command can be customized by modifying the scripts/build.min file within your site directory.

clean

Deletes all files and directories in the output and temp directories.

Note

This command can be customized by modifying the scripts/clean.min file within your site directory.

init

Initializes a new HastySite site directory, by creating the following directory structure:

Tip

Default folder paths can be configured in your settings.json file.

page

Generates an empty page content file containing initial metadata. This command asks the user for the following information:

After information has been provided, a new content will be created in the contents directory containing the following metadata properties:

Note

This command can be customized by modifying the scripts/page.min file within your site directory.

post

Generates an empty post content file containing initial metadata. This command asks the user for the following information:

After information has been provided, a new content will be created in the contents/posts directory containing the following metadata properties:

Note

This command can be customized by modifying the scripts/post.min file within your site directory.

Options

By default, HastySite provides the following options to display information about the program or alter its behavior.

-h, --help

Displays the description of all HastySite commands and options.

-l=level, --loglevel=level

Sets the log level to one the following values:

-v, --version

Displays the HastySite version string.

Customization

By default, HastySite provide all the scripts and rules necessary to build a simple blog with static pages and timestamped blog posts. While this may work for a simple blogging site, you may need additional features like support for tags, or maybe group articles by months, or project pages with custom metadata, and so on.

HastySite can be customized to your heart content essentially in the following ways:

Default Build Pipeline

Before diving into customization techniques, you should be familiar with the way HastySite builds your site out-of-the-box. If you have a look at the scripts/build.min file, it looks like this:

;Builds a site by processing contents and assets.
'hastysite import

"Preprocessing..." notice
preprocess
"Processing rules..." notice
process-rules
"Postprocessing..." notice
postprocess
"All done." notice

Even if you are not familiar with the min programming language, this code looks straightforward enough. as part of the build process, three actions are performed:

  1. preprocess
  2. process-rules
  3. post-process

Preprocess

During this phase, the following operations are performed:

  1. Some maintenance of temporary files is performed, e.g. the temp directory is created and populated with a checksums.json file if needed, temporary contents from the previous build are deleted, and so on.
  2. All contents are loaded, and metadata in the content header is processed and saved in memory.
  3. All assets are loaded and bare-bones metadata is generated for them and saved in memory, as they have no header.

If you are wondering what this content header is, it’s a section at the start of a content file delimited by five dashes, and containing metadata properties, like this:

-----
id: getting-started
title: "Getting Started"
content-type: page
-----

Now, this looks like YAML, but it is actually Nim’s own configuration file format, which is a bit more limited, but it does the job. Just remember to wrap strings with spaces in double quotes and everything will be good.

Internally, after the preprocessing phase all contents and assets will have the following metadata:

id
An identifier for the content or asset, corresponding to the path to the file relative to the contents or assets folder, without extension.
path
The path to the file relative to the contents or assets folder, including extension.
type
Either content or asset.
ext
The file extension (including the leading .).

Process Rules

In this phase, the control of the build process is passed to the rules.min script. It is important to point out that in case of an empty rules.min file, nothing will be done and no output file will be generated.

Luckily, a default rules.min file is provided, which:

Typically, you only need to modify this file to change how HastySite builds your site.

Postprocess

In this phase, the temp/checksums.json is updated with the latest checksums of the generated output files.

Modifying the rules.min File

The rules.min file is used to build your site. This file is nothing but a min script, and therefore you should have at least a basic understanding of the min programming language before diving in and modifying it.

In particular, you should get acquainted with the following min modules, whose symbols and sigils are typically used to create rules.min files:

Additionally, a dedicated hastysite module is also provided specifically for HastySite, which is described in the Reference section.

Creating Commands

Once you are comfortable with witing min scripts and maybe after you modified the rules.min file, you could try modifying or adding new HastySite commands. To do so, you must:

  1. Create a new .min file named after your command (e.g. project.min) and place it in the scripts folder of your site.
  2. On the first line, enter a min comment corresponding to the description of your command. This description will be used by HastySite help system.
  3. On the subsequent lines, write the logic of your command in min.

For more information and examples, have a look at the default scripts generated by the hastysite init command.

Leveraging HastyScribe Advanced Features

In some cases, you may not even need to edit .min files to customize the way your site pages are rendered. In particular, HastyScribe, the Markdown engine that powers HastySite, provide a lot of extra feature aimed at improving content reuse, such as:

Reference

This section provides some reference information related to the default metadata of contents and assets, as well as the full documentation of the hastysite min Module.

Default Content and Asset Metadata

The following table lists all the default metadata properties available for contents and assets, and also after which build phase they become available.

Note

You can define your own custom metadata for contents in a header section delimited by five dashes, at the start of each content file.

Property Content Asset
id
path
ext
type
title ^1
content-type ^1
date ^(1,2)
timestamp ^(1,2)
contents ^3 ^3
  • 1 This property is defined for all page and post contents created using the default page and post commands.
  • 2 This property is defined for all post contents created using the default post command.
  • 3 This property must be added to contents and assets before they can be written to the output folder. This can be done implicitly using symbols provided with the hastysite min module.

hastysite min Module

This min module can be imported in the rules.min file or in any script file and can be used to perform common operations such as ready and writing files, and interact with HastySite data at build time.

assets

∅ ⇒ (meta*)

Returns a quotation of metadata dictionaries (meta*) containing the metadata of each asset file.

clean-output

∅ ⇒ ∅

Deletes all the contents of the output directory.

clean-temp

∅ ⇒ ∅

Deletes all the contents of the temp directory.

contents

∅ ⇒ (meta*)

Returns a quotation of metadata dictionaries (meta*) containing the metadata of each content file.

input-fread

meta ⇒ string

Reads the contents of the file identified by the metadata dictionary meta (such as those returned by the contents and assets parameters).

Note that:

markdown

string1 dict ⇒ string2

Converts the HastyScribe Markdown string string1 into the HTML fragment string2, using the properties of dict as custom fields (accessible therefore via HastyScribe’s {{$<field-name>}} syntax).

mustache

string1 dict ⇒ string2

Renders mustache template string1 into string2, using dictionary dict as context.

Note

string1 is the path to the mustache template file, relative to the templates directory and without .mustache.

output

∅ ⇒ string

Returns the full path to the output directory.

output-cp

meta ⇒ ∅

Copies a file from the source directory (contents or assets depending on its type) to the output directory.

Note that:

output-fwrite

meta ⇒ ∅

Writes the contents of the file identified by the metadata dictionary meta (such as those returned by the contents and assets parameters).

Note that:

postprocess

∅ ⇒ ∅

Starts the postprocessing phase of the build.

preprocess

∅ ⇒ ∅

Starts the preprocessing phase of the build.

preprocess-css

string1 ⇒ string2

Pre-process CSS contents within string1, i.e.:

  1. Pseudo-SCSS partial imports. Partial CSS files must start with an underscore and be placed in the css-partials directory (set in your settings.json, or assets/styles if not specified).
  2. CSS variable declarations

Returns the resulting CSS code string2.

For example, the following CSS code in two different files:

_vars.css:
:root {
   --standard-gray: #cccccc;
}
style.css:
@import 'vars';
.note {
  background-color: var(--standard-gray);  
}

Will be converted into the following:

:root {
  --standard-gray: #cccccc;
}

.note {
  background-color: #cccccc;  
}

Limitation

Only basic support for CSS variables is provided, e.g. no fallback values are supported.

process-rules

∅ ⇒ ∅

Starts the processing phase of the build, and interprets the rules.min file.

settings

∅ ⇒ dict

Returns a dictionary dict containing all the settings defined in the settings.json file.

Changelog

v1.3.9

v1.3.8

v1.3.7

v1.3.6

v1.3.5

v1.3.4

v1.3.3

v1.3.2

v1.3.1

v1.3.0

v1.2.2

v1.2.1

v1.2.0

v1.1.0

v1.0.1

Just a bugfix release, containing minor fixes to the default CSS stylesheet, and upgrades to HastyScribe v1.7.1 and min v0.13.0.

v1.0.0

This is the first public release of HastySite. There are not many things changed compared to the previous release, except for the brand new HastySite web site available at https://hastysite.h3rald.com.

The contents of the site are also available in a standalone HTML document, here.

v0.1.0

The first internal release of HastySite is out and available on Github. This is intented to be only an internal pre-release, but as a matter of fact everything works as expected.

This first release has already been tested in production on the following web sites: