A minimalist personal static site generator with an opinionated feature set.
A minimalist personal static site generator.
This is an attempt to write the simplest possible static site generator that satisfies my own personal use cases and needs. It is not meant as a general purpose solution, and common site generation features which I don't use have been purposefully left out. Use at your own risk
As mentioned above, the feature set of Cork is very much tailored to my personal site needs, and so purportedly table-stakes features of competing static site generators may work differently or be entirely absent here. If you want a more friendly, generalized, or feature-rich static site generator, I suggest Jekyll or Hugo, both of which I've used in the past and found excellent.
Warnings aside, Cork supports the following.
Markdown and Mustache #
Cork expects that pages of the site will be written in Markdown, and templated with Mustache. It also supports regular html pages, but the general idea is to define Mustache templates and reference them from content containing markdown files.
YAML Front Matter #
Speaking of references, Cork allows for YAML front matter to be specified at the beginning of every markdown file. This YAML content lets you set predefined variables (such as
template to specify the mustache template to use for the page in question during site generation), as well as create custom variables which are accesible in the content of the post via standard "double mustache" syntax.
Minimal Assumptions #
In terms of site structure, Cork makes minimal assumptions. Other than putting the site in the
web/ directory, the only other requirement is that you put your templates in the
All the rest of the site's structure is up to you. Keep in mind that the folder layout you choose within
web/ will be mimiced in the generated site, meaning that putting a blog post in
web/post/post1.html will result in a final url of
Note that depending on where you host your generated site, the humanized
www.sitename.com/post/post1 url will also work, but if not you can explicitly make it work by storing the post at
web/, and responsible for ensuring those locations line up with references to the assets in your templates and html files.
Old School Themes #
A result of the lack of assumptions is that there is no built-in support for themes like you get with a lot of other static site generators. Instead, you are responsible for adding whatever CSS, JS, and templates are necessary to achieve the look you want.
Dart Scripting #
Autogenerated Metadata #
Cork provides some autogenerated metadata which can be transcluded in post content and templates if desired, or ignored if not. These metadata variables always start with
CORK_, and currently include:
CORK_url: the relative url of the page in question
CORK_reading_time: the average calculated time it will take to read the page in minutes
CORK_*_readability_score: calculations of various readability scores over the page content
See the longform post in the example site for sample usage.
Finally, Cork enables transclusion of files within Markdown content, similar to Mustache's Partials. This is useful if you wish to include an entire file (such as a script, code, or data file) within the body of a post.
Since this tool uses Dart, you first need to install the Dart SDK.
Once dart is installed, create a new folder for the site, and add a
pubspec.yaml file like you would for any new Dart project:
~> mkdir my_site ~> cd my_site ~> touch pubspec.yaml
pubspec.yaml file, add Cork as a dependency, along with the necessary build runners dependencies:
name: my_site dependencies: cork_site: ^1.0.0 build: any dev_dependencies: build_runner: any build_web_compilers: any
Site Creation #
Next, create a
web/ folder to hold your site's contents, and add some content. See the
example/ folder for a sample site.
mkdir web vim web/index.md ... add templates, css, markdown posts, etc
Site Generation #
Finally, to generate your site, there are two options.
Start by fetching any missing dependencies.
Development Hot Reload #
Then, while working on your site, you can run a development server which live-reloads your changes
pub run build_runner serve
Production Release #
When you're ready to generate a finished release of the site, run
pub run build_runner build --release --output <OUTPUT_FOLDER_LOCATION>
See the example folder for an example of a site build using Cork, as well as a sample layout.