Fediversity/website

Fediversity web site

This web site is built with a static site generator based on the Nix language module system. It has unique features such as:

• correct-by-construction relative links, automatic redirects for moved pages
• correct-by-construction content fields
• customisable templating and content structure, all seamlessly expressed in the Nix language
• correct-by-construction spec-compliant HTML output
• content source organisation independent of output structure

Structured content is managed through Nix expressions, and copy is written in CommonMark.

Contributing

• Install Nix

• Set up direnv

• Run direnv allow in the directory where repository is stored on your machine

  Note

  This is a security boundary, and allows automatically running code from this repository on your machine.

• Start a live preview in a different terminal:

  devmode
  

  This will open your default web browser and automatically reload the page when the source changes.

• Edit any of the files, see repository layout for guidance

Testing

As a derivation, e.g. for CI:

nix-build -A tests

In the development shell:

run-tests

Running tests in a loop on source code changes:

test-loop

Repository layout

• content

  Content of the web site is managed here. The entry point is content/default.nix and is built to correspond to index.html in the result. All other content sources are automatically included in imports, and can be accessed though the config module argument.

• structure

  Definitions of content data structures, such as pages, articles, menus, collections, etc.

• presentation

  Code specific to how the web site is rendered. In particular, it encodes the mechanism for distributing content to files, and for putting together files for the final result.

  In principle, different output formats (such as RSS feeds) are possible, and would be implemented there.

• default.nix

  Entry point for building the project. This is where content, structure, and presentation are wired up.

• shell.nix

  Convenience wrapper to enable running nix-shell without arguments.

• lib.nix

  Reusable convenience functions. Also exposed under the lib attribute in default.nix.

• npins

  Dependencies, managed with npins.

• README.md

  This file.