Add project structure documentation

README.md

@@ -1,9 +1,29 @@
-# Angestöpselt Homepage
+# Angestöpselt Homepages
 
-This repository contains the next version of Angestöpselt's homepage, intended
-to be hosted at <angestoepselt.de>. It is built with the
-[Eleventy](https://www.11ty.dev/) static site generator, using SCSS for
-stylesheets.
+This repository mainly contains the next version of Angestöpselt's homepage, intended to be hosted at <angestoepselt.de>.
+It is built with the [Eleventy](https://www.11ty.dev/) static site generator, using SCSS for stylesheets.
+It also hosts the site for [CoderDojo Würzburg](https://coderdojo-wue.de).
+
+## Project structure
+
+The project's directory tree is structured as follows.
+Note that this repository contains code to build different sites with some shared elements.
+
+- **assets/** – Shared static content. This will be copied into the `assets` directory when building any site.
+- **cgi-bin/** – CGI scripts. These are shared between sites, but not every site makes use of all the scripts. Note that these should not be called directly by site visitors. Rather they are called by rewriting paths in the server configuration where appropriate.
+- **includes/** – Directory for [Eleventy includes](https://www.11ty.dev/docs/config/#directory-for-includes). This contains layouts and template files.
+- **nix/** – Auxilliary build files used by the [Nix](https://nixos.org/) package manager.
+- **playground/** – This directory contains anything that shouldn't be included directly but might be relevant to the project.
+- **sites/** – Each site gets a subdirectory here containing its content.
+  - **&lt;name&gt;**
+    - **_assets/** – Site-specific static content. This will also be copied into the `assets` directory of the final output.
+    - **_data/** – Directory for Eleventy [global data files](https://www.11ty.dev/docs/data-global/).
+    - **_images/** – Place images that should be rendered by the build system in some way here.
+    - **httpd.conf** – Configuration file for [lighttpd](https://redmine.lighttpd.net/projects/lighttpd/wiki#Documentation), which will serve the final site.
+    - *Anything else* is actual content for the site (usually in the form of markdown files).
+- **styles/** – SCSS stylesheets. Anything directly in this directory that doesn't begin with an underscore will be available in the final build.
+- **.eleventy.js** – Base Eleventy configuration. This is set up so that the correct paths for the selected site (according to the environment variable `SITE`) are selected automatically.
+- **.eleventyignore** – Eleventy ignore file. Place paths in here that should be excluded in the final build.
 
 ## Local development environment
 
@@ -13,7 +33,7 @@ with version 14). Then run:
 ```shell
 npm install
 npm run build:styles
-npm run dev:site
+SITE=angestoepselt npm run dev:site
 ```
 
 Go to <https://localhost:8080/>, which will update live when content changes
@@ -27,16 +47,14 @@ terminal to watch for changes.
 This repository also contains a [Nix flake](https://nixos.wiki/wiki/Flakes)
 which contains the full development environment. `nix develop` will open a
 shell with all required tools – you don't need to run `npm install` anymore.
-Run `nix build ".#angestoepseltSiteEnv" -o .dev` to get a running Node
-environment in the _.dev_ folder (for example to configure an IDE).
+Run `nix build ".#devEnv" -o .dev` to get a running Node environment in the
+_.dev_ folder (for example to configure an IDE).
 
 When Node dependencies are updated (this will change `package.json`), make sure
-to run `./_nix/update.sh` to update the npm lockfile and the Nix environment.
+to run `./nix/update.sh` to update the npm lockfile and the Nix environment.
 
 The flake also contains a second package for building the production output:
 
 ```shell
-nix build # Will create an output derivation in 'result'
+nix build  # Will create an output derivation in 'result'
 ```
-
-The final derivation contains a `www` folder that can be served.