A static page generator made with hoast
. It is build to be simple, understandable, and functional out of the box in order to serve a basis to be changed by others to create a workflow that fits their needs as well as show the power of hoast.
The system builds by layering source directories in order to modularize site content and site layouts. It supports all the basic which you might expect from a static page generator. First gray-matter
is used to extract front matter from markdown files. markdown-it
is used to convert the content. handlebars
enters the content into layouts. Finally all CSS, HTML, and JavaScript files are minified using clean-css
, html-minifier
, and terser
respectively.
To use the command line interface you need to install the tool either locally or globally using the npm package manager which comes prepackaged with Node.js. After you have installed node run the following command to install the package globally with npm i -g hoastig
or locally with npm i --save hoastig
.
If you install it globally you can use the hoastig [options]
command from anywhere on your device. Try running hoastig --help
to see what commands you can use or see the overview below.
If you install it locally you can use the node node_modules/hoastig/bin/hoastig
command from that package, so you can easily se a build command up in the package.json
. To see what commands you can use see the overview below.
Options
-V, --version output the version number
-h, --help output usage information
-c, --config <path> path to configuration file (default: hoastig.json)
-d, --development process files in development mode
-r, --remove remove destination directory beforehand
See development mode for more information about the
-d
and--development
options.
If for any reason you want to use the static page generator as part of node application install it locally using npm i --save hoastig
. After which you should be able to require it and call the asynchronous hoastig(directory[, config, options])
function. See the table below for an explanation of each parameter as well as an example.
Options
directory
: Path to directory to work from, most likely__dirname
.- Type:
String
- Required:
yes
- Type:
config
: Configuration, see configuration for more details.- Type:
Object
- Required:
no
, see configuration section for default values.
- Type:
options
: Process options.development
: Process in development mode.- Type:
Boolean
- Default:
false
- Type:
remove
: Remove the destination directory before processing.- Type:
Boolean
- Default:
false
- Type:
Example
import hoastig from "hoastig";
const config = {},
options = {};
hoastig(__dirname config, options);
The function is asynchronous and can therefore be used in combination with the
await
keyword.
The development mode is activated when the -d
or --development
options is set when using the command line interface, or the options.development
boolean is set to true when using script. The difference between normal build mode and development build mode are listed below.
- If
development.concurrency
is set it will overrideconcurrency
. - If
metadata.base_url
is set it will be overwritten using thedevelopment.address
anddevelopment.port
. - Minification of the
.css
,.html
, and.js
will be disabled.
destination
: The directory to write the processed files to. Forward slashes (/
) should be used as separators in the paths.- Type:
String
- Default:
dst
- Type:
sources
: The directories to process files from, whereby files in the directories later in the list overwrite files in the directories before it. Forward slashes (/
) should be used as separators in the paths.- Type:
String
orArray of strings
- Default:
[ "src" ]
- Type:
metadata
: Metadata given to the layouts.- Type:
Object
- Default:
{}
- Type:
highlight
: When set to true or to an object then highlighting of code blocks will be enabled. If set to an object the object will be given as configuration options tohighlightjs
.- Type:
Boolean
orObject
- Default:
false
- Type:
minify
css
: Options for clean-css.- Type:
Object
- Default:
{}
- Type:
html
: Options for html-minifier.- Type:
Object
- Default:
{ "collapseWhitespace": true, "removeComments": true }
- Type:
js
: Options for terser.- Type:
Object
- Default:
{}
- Type:
rename
prettify
: Whether to prettify the file paths for the web. For example going fromarticle.html
toarticle/index.html
.- Type:
Boolean
- Default:
true
- Type:
underscore
: Whether to remove the underscore at the start of file names in the content directory.- Type:
Boolean
- Default:
false
- Type:
concurrency
: Maximum number of files to process at once.- Type:
Number
- Default:
Infinity
- Type:
development
concurrency
: Override forconcurrency
during development mode.- Type:
Number
- Default:
undefined
- Type:
host
: Address to use during development mode.- Type:
String
- Default:
localhost
- Type:
port
: Process to use during development mode.- Type:
Number
- Default:
8080
- Type:
The
css
andjs
options will also be given to thehtml
minifier to use for CSS and JS content within files given to it.
Defaults
{
"destination": "dst",
"sources": [
"src"
],
"metadata": {},
"highlight": false,
"minify": {
"css": {},
"html": {
"collapseWhitespace": true,
"removeComments": true
},
"js": {}
},
"rename": {
"prettify": true,
"underscore": false
},
"concurrency": Infinity,
"development": {
"concurrency": undefined,
"host": "localhost",
"port": 8080
}
}
When using the command line interface the configuration can be specified in a .json
file. By default this will retrieve a hoastig.json
in the directory the command is executed from, this can be overwritten using the -c
or --config
option. For more detail see the configuration section.
The destination directory is the directory relative to where the program is executed from and can be defined in the configuration file.
The source directories are a list of paths relative to the where the program is executed from and can be defined in the configuration file. This list can used to split parts of a site up in, for instance a theme and content directory. Each directory in the list will overwrite the previous one in the order they are provided in if duplicate files are found. Each source directory follows the following pattern of optional sub directories and files.
content
: Content files, each file will be transformed into a page. Files should have the.hbs
,.html
, or.md
extension. Extension are eventually converted to.html
if they are not already. Extension can also be chained so that a markdown file can include handlebar partials for instance. For examplepage.hbs.md
will first be transformed from markdown to html, then it will be read as handlebars and transformed to html again, this time giving it the.html
extension. Finally the resulting or pre-existing.html
files will be minified.decorators
: Handlebar decorators. Files should have the.js
extension. The file should export a single handlebars decorator compatible function.helpers
: Handlebar helpers. Files should have the.js
extension. The file should export a single handlebars helper compatible function.layouts
: Handlebar layouts. Files should have the.hbs
extension.partials
: Handlebar partials. Files should either have the.hbs
or.html
extension.static
: Files in this directory will be transferred over to the root of the destinations directory..ccs
,.html
, and.js
will be automatically minified.metadata.json
: A JSON file containing metadata for the layout context> Theconfig.json
's metadata will be deeply assigned over this.
Any files put in the root of a source directory or sub directories not specified in the list above will be ignored by the program. This is useful for storing any
README.md
or other miscellaneous files.
├── dst/
├── src/
│ ├── content/
│ ├── decorators/
│ ├── helpers/
│ ├── layouts/
│ ├── partials/
│ ├── static/
│ └── metadata.json
└── hoastig.json
hoastig.json:
{
"destination": "destination",
"sources": [
"themes/theme",
"site"
]
}
Directory structure:
├── destination/
├── site/
│ ├── content/
│ └── static/
└── themes/
│ └── theme/
│ ├── helpers/
│ ├── layouts/
│ ├── partials/
│ ├── static/
│ └── metadata.json
└── hoastig.json
Do note the paths given to
sources
always use forward slashes as separators no matter the platform. Secondly any files in thethemes/theme
directory also present in thesite
directory are overwritten, because of the order specified under sources in thehoastig.json
.
The context provided to the Handlebars files exists out of the meta data from the configuration file, values generated by hoastig, and the files front matter all merged into one object. The overview below shows which values are generated by hoastig during the building process.
content
: Content of the file.- Type:
String
- Type:
excerpt
: Excerpt of the content of the file. This can be marked down in the content of the file by using three hyphens after the front matter section of the file.- Type:
String
- Type:
Examples
Markdown files content:
---YAML
title: Lorem ipsum
---
Donec vulputate imperdiet aliquet. Fusce ac felis feugiat, sodales nisi id, vestibulum erat.
---
Maecenas congue, velit nec ultrices consectetur, dolor justo scelerisque augue, sed varius orci quam nec quam.
* Morbi tincidunt
* Enim lobortis
Resulting Handlebars context:
{
title: "Lorem ipsum",
content: "<p>Donec vulputate imperdiet aliquet. Fusce ac felis feugiat, sodales nisi id, vestibulum erat.</p>\n<p>Maecenas congue, velit nec ultrices consectetur, dolor justo scelerisque augue, sed varius orci quam nec quam.</p>\n<ul>\n<li>Morbi tincidunt</li>\n<li>Enim lobortis</li>\n</ul>",
excerpt: "Donec vulputate imperdiet aliquet. Fusce ac felis feugiat, sodales nisi id, vestibulum erat."
}
site_url
: When the development option is set this will be set to the development host and port set in the configuration. Recommended to be set in the meta data of the configuration file as well.- Type:
String
- Type:
base_url
: The relative directory path to the page from the root of the destination directory. Ifsite_url
is set it will be prepended to this value to create an absolute url.- Type:
String
- Type:
page_url
: The relative file path to the page from the root of the destination directory. Ifsite_url
is set it will be prepended to this value to create an absolute url.- Type:
String
- Type:
Examples
For a file at path content/example.md
:
{
base_url: "/example/",
page_url: "/example/index.html"
}
For a file at path content/example.md
with rename.prettify
set to false
:
{
base_url: "/",
page_url: "/example.html"
}
For a file at path content/example.md
with site_url
set to https://example.com
:
{
site_url: "https://example.com",
base_url: "https://example.com/example/",
page_url: "https://example.com/example/index.html"
}
For a file at path content/example.md
with the development
option set to true
:
{
site_url: "https://localhost:8080",
base_url: "https://localhost:8080/example/",
page_url: "https://localhost:8080/example/index.html"
}
- Not compatible with pnpm a fast and disk space efficient alternative to the npm.