kronk
v0.1.2
Published
A pretty simple static site generator
Downloads
12
Maintainers
Readme
Kronk, a simple static website generator
Kronk helps you create your static website, be it a blog or any other kind of presentational content that don't really require any kind of logic.
It was built on the assumption that batteries included are always nice but are also a pain to learn, which is why it tries to provide a very simple way of working that allows for complicated things to be achieved without much hassle.
This is why this documentation is on the light side ; kronk simply does not do much.
It uses the following great software :
- Pug for templating (formerly known as jade)
- Markdown-it for the markdown side
- Json5 because it is nicer than plain json
- Toml because choice is good
- Yaml because even more choice is even better
Table of Contents
TL;DR
$ npm install -g kronk
$ git clone https://github.com/ceymard/kronk-sample-site
$ cd kronk-sample-site
$ kronk
For kronk to build a site, it needs a package.json
file at the root of the project with
at least a "kronk": {}
entry in it. This variable can hold the following values ;
// ...
"kronk": {
"src": "<the directory containing the site sources, defaults to 'src'>",
"template": "<the directory containing the pug templates, defaults to 'template'>",
"build": "<the directory where the generated files will be placed, defaults to 'build'>"
},
// ...
Kronk uses a package.json
for its configuration to allow you to install libraries that
you can use in javascript files in the src
directory. The configuration object contains only
paths ; this is because the behaviour altering options are always defined in metadatas.
When run, kronk will look up the package.json, read all the files in the src
directory
and render all those that do not start with _
and that have either the .md
or .pug
extensions into the build
directory.
Note that all the files are read, even those that will not be rendered. This is so that those that will be can still access their metadata in their templates.
To get a hang of kronk, try cloning the sample project.
All files in kronk are associated to metadata. Some files are even pure metadata. What you put in it is entirely up to you, as we make no assumption what you should use.
The only exception is the kronk
object, as its value can change the way
kronk behaves.
Like hugo or jekyll, kronk allows you to define metadata in the very files that are to be rendered at their begining. A simple marker is used before and after the metadata that indicates which format we deal with.
We use +++
for toml, ---
for yaml and ...
for json.
In the case of json, the {
and }
surrounding the object are optional.
In pug templates we can access this metadata directly as it is injected into the locals.
---
// This is a yaml metadata section.
title: my title
---
h1 Displaying the title : #{title}
p.
This file's name is "#{$file.name}". In its directory, there are probably
others. Here are their name :
ul
each file in $files.in($file.dirname)
li ${file.name}
In addition to the metadata defined in this file and inherited via __meta__
files,
two variables are passed to the template : $file
which is a File instance, and
$files
which is a FileArray instance.
Sometimes, it is useful to define a file that is pure data and is not meant to be rendered.
Kronk reads files with extensions json
, json5
, yaml
, yml
, toml
and js
.
Their content is parsed and put into the file.meta
variable. In the case of .js
files,
they are require()
'd and the resulting module.exports
is put into file.meta
.
Whenever a __meta__.{json|json5|yaml|yml|toml|js}
file is defined in a directory,
all the other files in the same directory will deep merge their content into their own metadata.
The metadata defined in a template file has precedence over the __meta__
files.
Subdirectories inherit their parent directory's __meta__
files. It is thus possible to have
a hierarchy of __meta__
files that get enriched the further down the tree we go. When merging,
children have priority over parents.
For instance, in the following example, index.pug merges the __meta__.json
's contents into
its own metadata and that's it.
file1.md
and file2.md
however will have the contents of __meta__.json
and __meta__.yml
merged
into their own metadata.
.- __meta__.json
|- index.pug
|-. docs
|- __meta__.yml
|- file1.md
`- file2.md
To allow for maximal flexibility, you can have plain javascript files in your src/
directory.
These files are not rendered like .pug
or .md
files ; instead, kronk expects their module.exports
to be a function and runs it at render time.
// Example of a javascript file that uses a template not normally rendered to
// render it multiple times.
/**
* @param $file: the current file object
* @param $files: The global files array
*/
module.exports = function ($file, $files) {
var template = $files.get('docs/_category')
for (var meta of $files.in('docs').map(f => f.meta)) {
template.render({
output_filename: `docs/category_${meta.tag}.html`,
// ... add some other variables for the template to use
})
}
}
.js
files can also be used as a __meta__.js
entry, which will then use the module.exports
as the meta object.
Markdown files are generated and injected into a pug template. By default, this template is ;
extends /markdown.pug
block markdown
| ... the result of
| the generation of the markdown is put here.
This pug template uses the local metadata as well, which means that interpolation in your markdown
is possible using the #{variable}
syntax.
If you wish to override these defaults, use the kronk.markdown_template
and kronk.markdown_block
file metadata variables.
Note that by default there is no code highlighting included ; you will have to use
a __meta__.js
file including highlight.js
or another highlighting library into the
kronk.markdown_options
object.
When kronk is run, all the files of the src
directory are added to a file array.
This array is passed to all the templates as the $file
variable so that a file
may access other files and play with them.
Methods
get(name: string): File
Gets the file object of the same name.null
if the file does not exist. All files can be accessed this way, even the pure data ones.in(dir: string, shallow = false): FileArray
Filter the files to only include the files in the specified directory and its children. Ifshallow
is true, do not descend into subdirectories.renderable(): FileArray
Only the renderable files
The file object holds informations about a file that has been read by kronk. This object
is always injected into the template's metadata when rendering as $file
.
Methods
renderable(): boolean
true if the file can be rendered (usually just because it is markdown or pug)render(meta: object = {}): void
render the file to the file system, merging the additionnal meta to thefile.meta
. This does not changefile.meta
.
Properties
name: string
the name of the file with its path relative tosrc/
but without extensionbasename: string
the basename of the filenoextbasename: string
the basename without extensionpath: string
the absolute path of this fileext: string
the file extensiondirname: string
the directory name relative tosrc/
stat: StatObject
the stat as returned byfs.stat()
contents: string
the original contents of the file without the metadata sectionmeta: object
the parsed metadata with__meta__
files already merged into it. not enumerable$files: FileArray
the FileArray this File belongs to. not enumerable
Some metadata values are interpreted by kronk and not left only to your templates.
They all live inside the kronk
object to avoid clashing with your own naming.
kronk.output_filename
the name of the file that will be written inbuild
whenrender()
is called on this file. default<$file.name>.html
kronk.markdown_template
is the name of the pug template in which a markdown file will be injected. default/markdown.pug
.kronk.markdown_block
is the name of the block inside the markdown template. default'markdown'
kronk.markdown_options
the options object given to markdown-it. default{}
kronk.pug_options
the options object given to pug compile function. default{}