[ANN] YOCaml, a framework for static site generator

Community
1

:wave: Hello everyone! We, the YOCaml development team, are very pleased to announce the release of version 2, freshly merged into opam-repository :champagne:!

YOCaml is a framework for describing static site generators (a very small applicative build-system whose API is tailor-made for creating web pages ) and its internal model is very similar to Hakyll (the 3th version), another Haskell framework. (a presentation was given to the OCaml user Group in Paris and you can find the video, in French, here).

Changes with 1.0.0

Historically, YOCaml was written very, very quickly to give examples of slightly exotic uses of the library Preface. Due to its experimental nature, the API was a bit laborious, but we did find some users! We took advantage of the redesign to stop relying on Preface (and yes, YOCaml was already more widely used than Preface), move to OCaml 5.x and take advantage of user-defined-effects and support dynamic dependencies. In other words, YOCaml 2.0.0 is not at all compatible with version 1…

Plugins and runtimes

The aim of YOCaml is to be very generic and to allow users to bring their own dependencies, but we’ve taken the opportunity to release it with several plugins and runtimes so that it can be used directly.

Runtimes

A Runtime is an ‘execution context’ and generally exposes the primitive used to execute a YOCaml program. YOCaml 2 is bundled with 3 Runtimes:

  • Yocaml_unix: the default runtime, whose preview server is implemented on top of the brand new httpcats!

  • Yocaml_eio: a runtime iso to Unix but based on eio and whose preview server is described by cohttp_eio.

  • Yocaml_git: a parameterised runtime for generating a site directly in a git repository, which can be served, for example, by a Mirage (unipi), very well documented in this excellent article by @dinosaure!

Plugins

  • Yocaml_cmarkit provides a convenient API (via YOCaml) for converting Markdown files to HTML via the excellent cmarkit library.

  • Yocaml_omd provides a convenient API (via YOCaml) for converting Markdown files to HTML via the excellent OMD library (but we recommend yocaml_cmarkit).

  • yocaml_yaml provides a convenient API (via YOCaml) for reading Yaml via the excellent library ocaml-yaml

  • yocaml_otoml provides a convenient API (for YOCaml) for reading TOML via the excellent library Otoml

  • yocaml_mustache provides a convenient API (via YOCaml) for using Mustache as a template language via the excellent library ocaml-mustache

  • yocaml_jingoo provides a convenient API (via YOCaml) for using Jingoo as a template language via the excellent library jingoo

  • yocaml_syndication that gives tool to generate feeds (Atom, RSS 1 and 2 and OPML). The library is inspired by Syndic but does not depend directly on it.

A final word

YOCaml 2 was mainly written by xhtmlboi, helped by gr-im, mspwn and dinosaure with occasional support from maiste. It has already been used experimentally in a number of small projects:

You will also find extensively documented examples in the examples directory.

To conclude, we find (not very objectively) that YOCaml is a lot of fun to use, and it’s very cool to make your site using as much OCaml as possible.

Happy Hacking!

22 Likes
2

Nice work. I couldn’t find any documentation about how to use it, aside from the examples directory which contains excellent explanations but is harder to scan/digest. Do you have anything online or planning to put anything?

Thanks and congrats on the release

2 Likes
3

Yes! Our aim was not to push back the release too much, but we’re going to invest some time in making a dedicated site with examples and explanations! Right now, there’s already a tutorial for building custom data models : yocaml 2.0.0 (latest) · OCaml Package

Thank you so much for your support!

1 Like