Features

18 Sep 2016

Clean separation of concerns

A styx site is mainly managed in a single site.nix file. site.nix is divided in multiple parts, each one handling a special aspect of the site.

In the data section, external data files are fetched and data structures are declared.
The pages section controls the page that will be generated.

The configuration of a site is managed in an external conf.nix, where any of the used themes configuration interface can be used.

Themes

Themes are the main way to create and customize Styx sites, themes can provide:

Templates
Static files
Configuration interface
Function library

Themes can be combined in a modular way, making it is easy to personalize or extend an existing theme.

The generic-templates theme provide a template framework that can be used for quick website prototyping.

Themes from the styx-themes package set can be used directly without needing to be downloaded.

Content

Styx handle markdown and asciidoc content. Nix can also be used for structured data.

Markup files can declare metadata (front-matter) and easily declare introduction or multiples pages with dedicated separators.

Nix code can also be called in markup file, and this can be used to easily include external medias in content.

Template engine

Styx templates are written in the same language site.nix is written, the nix expression language.
A template is just a nix function returning text or an attribute set.

This make it very easy to include other template as it is just calling that template function:

''
  &lt;h1&gt;Foo&lt;/h1&gt;
  ${templates.bar}
''

Template functions can take arguments, so a list of post can be generated in the following fashion:

''
  &lt;h1&gt;Foo&lt;/h1&gt;
  ${mapTemplate templates.posts.list page.posts}
''

Every theme can provide templates functions, and new library functions that can be used in templates.

Configuration interface

Each theme can provide a configuration interface that can be used in the site configuration file. A theme configuration can profide extra information such as types and documentation. This allows to type-check configuration and to generate documentation for themes.

Interactive debugging

nix-repl can be used to inspect interactively any variable of a site.nix file.
Pages can be generated and the site can even be built from the repl.

$ nix-repl "<nixpkgs>"

nix-repl> site = callPackage (import ./site.nix) {}

nix-repl> site.conf
{ siteUrl = "https://styx-static.github.io/styx-theme-showcase"; theme = { ... }; }

Documentation

Styx is well documented, styx doc will lanch the documentation for the current version in a browser. It is also possible to generate a documentation for a site by using the styx site-doc command in the site directory.

Deployment facilities

Styx has a deploy sub-command that can be used to easily deploy a site to GitHub pages. Any styx site can also be deployed with NixOps.

Styx Site