Cork is a minimalist personal static site generator written in Dart that converts Markdown and HTML content into a static website using Mustache templates.
What is Cork?
Cork is an intentionally minimal static site generator built on the Dart SDK and the build_runner toolchain. It takes Markdown files with YAML front matter and HTML pages as input, applies Mustache templates from a web/templates/ folder, and outputs a static HTML site whose folder structure mirrors the source web/ directory. The project is authored by jasonrdsouza and published as the cork_site package on pub.dev. Cork is not a general-purpose generator: common features the author does not use are deliberately omitted.
Key Features
- Markdown and Mustache — Pages are written in Markdown and rendered through Mustache templates; plain HTML pages are also supported.
- YAML Front Matter — Every Markdown file can start with YAML that sets predefined variables such as
templateand custom variables accessible in content and templates. - Minimal Assumptions — The only structural requirements are that content lives in
web/and templates inweb/templates/; everything else is left to the user. - Old School Themes — There is no built-in theme system; you supply your own CSS, JavaScript, and templates to achieve the desired look.
- Dart Scripting — Dart Web scripts are automatically compiled to JavaScript, with samples in the example site demonstrating usage.
- RSS Feed Generation — Opt-in RSS 2.0 feed generation creates
/rss.xmlwhen configured inpubspec.yamland enabled per-post viarss: truefront matter. - Autogenerated Metadata — Cork exposes variables beginning with
CORK_, includingCORK_url,CORK_reading_time, and readability scores, for use in content and templates. - Transclusion — Files such as scripts, code, or data can be included inside Markdown content, similar to Mustache partials.
Who is it for?
Cork suits developers who want a static site generator that makes very few decisions for them. It is a good fit for Dart programmers who want to write client-side scripts in Dart and have them compiled to JavaScript, for personal site owners who already know Mustache and want full control over their markup, and for anyone who finds theme systems limiting and prefers to hand-write templates and CSS.
What can you do with Cork?
- Personal bloggers: Write posts in Markdown, add YAML front matter, and enable per-post RSS to generate a feed at
/rss.xml. - Dart developers: Use Dart Web scripts for interactive client-side features and let Cork compile them to JavaScript during the build.
- Self-hosted site owners: Control the final URL structure by placing files as
web/post/post1/index.htmlorweb/post/post1.html, then host the output anywhere.
How does Cork work?
First, install the Dart SDK. Then create a pubspec.yaml listing cork_site, build, build_runner, and build_web_compilers as dependencies. Create a web/ folder with Markdown and template files, run dart pub get, and use dart run build_runner serve for a live-reload development server or dart run build_runner build --release --output <OUTPUT> for a production build.
Pros and cons
- Pros: Very small feature surface; builds with Dart's standard build_runner; native Dart client-side scripting; automatic RSS generation; no imposed folder structure beyond
web/andweb/templates/. - Cons: No built-in themes; no general-purpose features; you must manage assets and template references yourself; assumes a Dart development environment.
Alternatives
The author explicitly suggests Jekyll, a Ruby-based generator widely used with GitHub Pages, and Hugo, a Go-based generator known for fast builds, as more feature-rich alternatives if Cork feels too minimal. Both are mature projects with large theme ecosystems.
FAQ
Does Cork require the Dart SDK?
Yes, Cork is a Dart package, so you must install the Dart SDK and use standard Dart build tooling. The build commands are dart pub get, dart run build_runner serve, and dart run build_runner build --release --output.
Can I use CSS and JavaScript with Cork?
You can place CSS, JavaScript, and other assets anywhere inside web/, and you are responsible for referencing them correctly in your templates and HTML files. Cork also compiles Dart Web scripts to JavaScript automatically.
Does Cork generate RSS feeds?
Yes, RSS 2.0 generation is opt-in. Configure cork_rss settings in pubspec.yaml and add rss: true plus a date to individual post front matter; the feed is output at /rss.xml.
Does Cork support themes?
No. Cork has no theme system; you are expected to create your own templates, CSS, and JavaScript. This is a deliberate design choice rather than a missing feature.
