Add an overview explaining the layout of the source code

README.md

@@ -7,10 +7,31 @@ website.
 Contents are written in Markdown, and rendered to static HTML at
 deployment time.
 
+# Overview
+
+To summarize quickly how the website is structured: it is a
+multi-language site, with the page language determined by the source
+file extension (.*lang*.md, where *lang* is the two-letter ISO code).
+As mentioned, pages are written in plain Markdown. If a page has some
+associated content, such as images, the best practice is to save those
+images under a new subdirectory of static/img/
+
+* `src/` contains the site sources
+* `static/img/` is for images, one subdirectory per associated content
+  page
+
+The pages are rendered using Bootstrap 5, with some Javascript
+functionality to support quick search and autocompletion:
+
+* `templates/` has the HTML templates (one for the documents, and one
+  for the search page)
+* `static/src/` contains the Javascript code and CSS customizations,
+  which are then compiled and minified using Webpack
+
 # Making changes
 
 The website contents are located in the `src` subdirectory. Pages are
-encoded in Markdown, with a small header providing page metadata
+written in Markdown, with a small header providing page metadata
 (mostly the page title).
 
 The header is YAML-encoded, and it must be separated from the page
@@ -27,20 +48,9 @@ there are some setup steps you will need to perform on your system.
 
 ## Requirements
 
-To build the website, a few tools will need to be installed:
-[gostatic](https://github.com/piranha/gostatic) to generate the HTML
-pages, and [sitesearch](https://git.autistici.org/ai/sitesearch) to
-generate the search index. The scripts will automatically download and
-install these tools if necessary, but you will need a working
-[Go](https://golang.org/) development environment.  Furthermore,
-testing the website requires running a local Apache server.
-
-On a Debian system, you can install all the requirements with:
-
-    $ sudo apt-get install rsync golang-go
-
-As an alternative for local testing, you can use Docker (see below) to
-avoid installing any of the above requirements locally.
+Docker is required to build the website. Since the result is a
+self-contained standalone web server container with no further
+dependencies, that makes it pretty easy to test locally too.
 
 ## Testing changes for correctness
 
@@ -68,52 +78,19 @@ these tests successfully:
 
 Simply run, from the top-level directory:
 
-    $ ./scripts/update.sh
+    $ docker build -t ai-website .
 
 The resulting HTML pages will be found in the `public` directory.
 
 ## How to run a test webserver
 
-### Docker
-
-The preferred way, which avoids installing an entire Debian
-distribution, would be to use Docker. Build the image with:
-
-    $ docker build -t ai-website .
-
-and run it with:
+Once you've built a container image (see *How to build the website*
+above), you can just run it locally with:
 
-    $ docker run --rm --network host ai-website
+    $ docker run --rm -p 8080:8080 ai-website
 
 the website should then be visible at http://localhost:8080/.
 
-### debootstrap
-
-To check the results of your edits, it is useful to start a local
-webserver to inspect the generated HTML pages. In general, you
-might want to avoid installing the Apache packages on your local
-system (especially on Debian where they automatically start
-daemons), so we have prepared a way to install Apache in a
-chroot. Run the following commands just once to set it up:
-
-    $ sudo apt-get install debootstrap
-    $ sudo ./scripts/install-apache.sh
-
-Then, to start Apache and the search daemon, run (it may ask
-you for your password due to the use of *sudo*):
-
-    $ sudo ./scripts/run-test-server.sh
-
-This will start a full server stack (web server and search server)
-that you can access by browsing to
-
-    http://localhost:3300
-
-To stop the Apache process when you're done, run:
-
-    $ sudo ./scripts/run-test-server.sh stop
-
-
 ## Embedding external data sources
 
 It is possible to use dynamically-generated data in the templates by
@@ -133,5 +110,3 @@ As an example of this technique, you can check out:
 * `data.d/dns`
 * `src/docs/web/domains.en.md_in`
 
-
-