Merge pull request #96 from earthstar-project/macromania

"macromania"

Author: sgwilym

.github/workflows/deploy.yml

@@ -15,12 +15,12 @@ jobs:
 
     steps:
       - name: Clone repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install Deno
-        uses: denoland/setup-deno@v1
+        uses: denoland/setup-deno@v2
         with:
-          deno-version: v1.x
+          deno-version: v2.x
 
       - name: Build step
         run: "deno task build"
@@ -29,4 +29,5 @@ jobs:
         uses: denoland/deployctl@v1
         with:
           project: "macromania" 
-          entrypoint: "./server.ts"
+          entrypoint: "./server.ts"
+          root: "."

.gitignore

@@ -1,2 +1,4 @@
-willowtest/build
-build
+# Automatically generated and populated by `deno build` or `deno watch`
+build
+.vscode
+rustdocs/cached_defs

.nova/Configuration.json

@@ -1,7 +1,5 @@
 {
-  "co.gwil.deno.config.formatOnSave" : "false",
-  "deno.enablePaths" : [
-    "willowtest",
-    "deno.json"
-  ]
+  "co.gwil.deno.config.formatOnSave" : "true",
+  "workspace.preview_type" : "custom",
+  "workspace.preview_url" : "http:\/\/localhost:8000"
 }

README.md

@@ -1,13 +1,21 @@
-# We Are Sorry
+# Willow-Specs
 
-This repository houses a completely undocumented, experimental macro expansion system for generating text documents. It also houses the source of [https://willowprotocol.org/](https://willowprotocol.org/), which augments the undocumented macro expander with a diverse set of undocumented macros, often of abysmal code quality.
+Source code for the specifications of [Willow](https://willowprotocol.org/).
 
-On the bright side, we consider the macro system a success and will eventually create a clean, well-documented, standalone version of it. Until then, unfortunately, the source for the Willow website (including for all the specifications) will stay rather inaccessible. We welcome issues on even the most trivial typo fixes, and will happily take care of them.
+The specs are written using [Macromania](https://github.com/worm-blossom/macromania) ([basic tutorial here](https://github.com/worm-blossom/macromania/blob/main/test/tutorial.tsx)), see this [Macromania demo repository](https://github.com/worm-blossom/demo_macromania) to learn about most of the macros used for this site.
 
-For the brave who do want to venture into the source:
+For working on the generated site, run `deno task watch` to rebuild the site on (most) changes to the source; build output is placed at `./build`. Run `deno task serve` to start a webserver at `localhost:8000` for seeing the effects of your changes. The `deno task watch` command detects changes to input `.ts` and `.tsx` files only, but not to assets such as images or stylesheets. When changing those, simply interrupt the current `deno task watch` command and run it again (the command always starts with a full rebuild).
 
-- The webpages themselves live in the [https://github.com/earthstar-project/tsgen/tree/main/willowtest/specs](https://github.com/earthstar-project/tsgen/tree/main/willowtest/specs) directory, with assets and css residing [one level higher](https://github.com/earthstar-project/tsgen/tree/main/willowtest).
-- The entrypoint to rendering the site is [`main.ts`](https://github.com/earthstar-project/tsgen/blob/main/willowtest/main.ts) (not to be confused with the *other* [`main.ts`](https://github.com/earthstar-project/tsgen/blob/main/main.ts) 🫠).
-- The macro expander is defined in [`tsgen.ts`](https://github.com/earthstar-project/tsgen/blob/main/tsgen.ts).
+## Source Organisation
 
-Again, we are sorry, but it is what it is.
+The entrypoint for macromania and the macromania expression that gets evaluated to produce the site is in [`src/main.tsx`]. Toward the end of that expression, we list the directory hierarchy of the website. The actual site contents are imported from hierarchically organised files in [`src/pages`]. Note how pages that have "subpages" (e.g. `src/specs.tsx`, `src/more.tsx`) are not mappend in a `<Dir>` macro, but "leaf pages" (e.g. `src/specs/data_model.tsx`) are. When in doubt, simply copypaste `src/specs/data_model.tsx` to get started with a new page.
+
+Assets are read from [`src/assets`]. Careful: [`src/assets/layout.css`] is actually autogenerated from [`src/layoutStyles.tsx`] at build time, and then copied from the assets directory into the build directory. It turned out to be less effort to do this way, even it breaks the reasonable assumption of assets being purely static. Oh well. If you need to modify the responsive layout of marginales, tables of contents, etc, do so in [`src/layoutStyles.tsx`]. Also, ideally, you shouldn't need to.
+
+The most common macros we use are those from the [scientific writing demo repository](https://github.com/worm-blossom/demo_macromania). Consult [`src/specs/data_model.tsx`] for usage examples of most of them. That file also demonstrates the macro we use for rendering paths.
+
+For example usage of the macro(s) for defining encodings, see [`src/specs/encodings.tsx`].
+
+In general, willow-specific macros are defined in [`src/macros.tsx`]. Usually, that's where you'll want to add new macros as well.
+
+The macro that serves as a general page template is defined in [`src/pageTemplate.tsx`].