From c9bdbfcb15b8c28a26ca3923aeea2e40aacc6b48 Mon Sep 17 00:00:00 2001
From: valentin gagarin <valentin.gagarin@tweag.io>
Date: Wed, 13 Nov 2024 15:24:41 +0100
Subject: [PATCH] add README

---
 README.md   | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 default.nix |  2 ++
 2 files changed, 72 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..845d52f8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# Fediversity web site
+
+This web site is built with a static site generator based on the Nix language [module system](https://nix.dev/tutorials/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](https://commonmark.org/).
+
+# Contributing
+
+- [Install Nix](https://nix.dev/install-nix)
+- [Set up `direnv`](https://github.com/nix-community/nix-direnv#installation)
+- Run `direnv allow` in the directory where repository is stored on your machine
+- Edit any of the files, see [repository layout](#repository-layout) for guidance
+- Build and view the web site
+
+  ```bash
+  xdg-open $(nix-build -A build --no-out-link)/index.html
+  ```
+
+  or
+
+  ```fish
+  open (nix-build -A build --no-out-link)/index.html
+  ```
+
+# Repository layout
+
+- [content](./content)
+
+  Content of the web site is managed here.
+  The entry point is [`content/default.nix`](./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](./structure)
+
+  Definitions of content data structures, such as pages, articles, menus, collections, etc.
+
+- [presentation](./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](./default.nix)
+
+  Entry point for building the project.
+  This is where content, structure, and presentation are wired up.
+
+- [shell.nix](./shell.nix)
+
+  Convenience wrapper to enable running `nix-shell` without arguments.
+
+- [lib.nix](./lib.nix)
+
+  Reusable convenience functions.
+  Also exposed under the `lib` attribute in [default.nix](./default.nix).
+
+- [npins](./npins)
+
+  Dependencies, managed with [`npins`](https://github.com/andir/npins/).
+
+- [README.md](./README.md)
+
+  This file.
diff --git a/default.nix b/default.nix
index 24ba832a..a750d3bc 100644
--- a/default.nix
+++ b/default.nix
@@ -16,6 +16,8 @@ let
   lib'' = lib.extend lib';
 in
 {
+  lib = import ./lib.nix { inherit lib; };
+
   build =
     let
       result = lib''.evalModules {