[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!

23 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
4

Hi, could you share the resource that holds the tutorial or example.

I saw your session at FunOCaml livestream

1 Like
5

Of course !

Currently the site needs some polish but it still readable, and we did not announce the site because we are awaiting for the release of 2.5.x (should come in the few days), but you can pin YOCaml to follow the tutorial :slight_smile:

3 Likes
6

That tutorial is just gorgeous :o

2 Likes
7

Thanks a lot!
And the Tutorial Website is also written using YOCaml (obviouslu :))

1 Like
8

Thank you xvw.

It needed to be 20 characters

1 Like
9

Release 2.5.0

We are delighted to present the new release of YOCaml: 2.5.0!
As you can see, there have been a few intermediate versions since our last announcement. However, we have reached a new milestone: YOCaml can now be used seamlessly with an Applicative API (instead of the Arrow one), making many tasks much easier to express!

We have also finally taken the time to write a tutorial that explains how to use YOCaml to create a complete blog, step by step, and our goal is to expand it over time to add more and more guides! (The documentation/guide generator (GitHub - yocaml/yocaml-www: A website for YOCaml (using, obviously, YOCaml) is also written in YOCaml and gives an idea of what can be done fairly quickly.)

We look forward to receiving your feedback! YOCaml is a free and collaborative project, so any contributions (including the guide) are more than welcome! We would also be DELIGHTED to see your creations with YOCaml!

Happy Hacking!

8 Likes
10

Thanks @xvw! The tutorial is really amazing :smile:

1 Like
11

I just noticed you guys added liquid template support using my liquid-ml package! That’s really cool, if you ever have any issues or feature requests with liquid feel free to reach out.

4 Likes