You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 
Nicolò Balzarotti 5e3c9b0ba0 add more tests 5 years ago
nixpkgs prefer sane defaults 5 years ago
scripts Themes documentation update 5 years ago
src elisp fixes + add tests 5 years ago
tests add more tests 5 years ago
themes cli: theme-path, doc updates 5 years ago
.gitignore documentation improvements, new functions 6 years ago
.gitmodules fetch themes 5 years ago
.travis.yml pin travis to nixos-unstable 5 years ago
LICENSE added the MIT license 6 years ago
VERSION 0.7.1 release 5 years ago
contributing.md cli: theme-path, doc updates 5 years ago
default.nix prefer sane defaults 5 years ago
derivation.nix better org->styx options export. BUT it not support lists and other 5 years ago
readme.md cli: theme-path, doc updates 5 years ago
release.md Fix tests 5 years ago
release.nix adding Hydra jobset file 5 years ago
roadmap.md fetch themes 5 years ago

readme.md

Build Status

Styx

The purely functional static site generator in Nix expression language.

Features

Among others, styx have the following features:

Easy to install

Styx has no other depency than nix, if nix is installed nix-env -iA styx is all that is required to install styx.

Multiple content support

Styx support content in markdown, asciidoc and nix format.
Styx also extends asciidoc and markdown with custom operators that can split a single markup file into many pages.

Embedded nix

Nix can be embedded in markup files!

Handling of sass/scss

Upon site rendering, styx will automatically convert sass and scss files.

Template framework

The generic-template theme provide a template framework that can be leveraged to easily create new themes or sites. Thank to this a theme like hyde consists only in about 120 lines of nix templates.

Configuration interface

Styx sites use a configuration interface a la NixOS modules.
Every configuration declaration is type-checked, and documentation can be generated from that interface.

Linkcheck

Linkcheck functionality is available out of the box, just run styx linkcheck to run linkchecker on a site.

Themes

Styx support themes. Multiple themes can be used, mixed and extended at the same time.
This make it very easy to adapt an existing theme.
Official themes can also be used without any implicit installation, declaring the used theme(s) in site.nix is enough!

Documentation

Styx embeds its complete documentation that can be viewed at any time by running styx doc.
A very unique feature of styx is that it can generate the documentation for a site with the styx site-doc.

Install

Use nix-env to install styx, or nix-shell to just test without installing it:

$ nix-env -iA styx
$ styx --help
$ nix-shell -p styx
$ styx --help

The version you will get will depend on the version of nixpkgs used, to get the latest stable release without relying on nixpkgs:

$ nix-env -i $(nix-build https://github.com/styx-static/styx/archive/latest.tar.gz)
$ styx --help

or

$ nix-shell -p $(nix-build https://github.com/styx-static/styx/archive/latest.tar.gz)
$ styx --help

Examples

The official styx site is an example of a basic software site with release news. It have some interesting features like:

  • generating the documentation for every version of styx
  • generating a page for every official theme

See site.nix for implementation details.

As a Nix laboratory

This repository is also a playground for more exotic nix usages and experiments:

  • derivation.nix is the main builder for styx, it builds the command line interface, the library, styx themes and the documentation.

  • script/run-tests is a thin wrapper to nix-build that will run library and functionality tests.

  • Library functions and themes templates use special functions (documentedFunction and documentedTemplate) that allow to automatically generate documentation and tests.
    The code used to generate tests from documentedFunctions can be found in tests/lib.nix.
    Library function tests can print a coverage or a report (with pretty printing):

    $ cat $(nix-build --no-out-link -A coverage tests/lib.nix)
    $ cat $(nix-build --no-out-link -A report tests/lib.nix)
    
  • scripts/library-doc.nix is a nix expression that generate an asciidoc documentation from the library documentedFunctions (example).

  • scripts/themes-doc.nix and src/nix/site-doc.nix are nix expressions that automatically generate documentation for styx themes, including configuration interface and templates (example). This feature is leveraged in the styx site-doc command to dynamically generate the documentation for a site according to used themes.

  • lib.prettyNix is a pure nix function that pretty print nix expressions.

  • parsimonious is used to do some voodoo on markup files to turn them into valid nix expressions, so nix expressions can be embedded in markdown or asciidoc.

  • styx propagatedBuildInputs are taken advantage in lib.data conversion functions like markupToHtml.

Contributing

See contributing.md.

Feedback

Any question or issue should be posted in the github issue tracker.
Themes and features requests are welcome! And please let me know if you happen to run a site on styx!