Merge branch 'main' into zach/stv-doc-update-wording

Author: robguthrie

.github/workflows/gh-pages.yml

@@ -20,6 +20,10 @@ jobs:
           mdbook-version: '0.5.2'
 
       - run: mdbook build en
+      - name: Check redirects
+        run: bash check-redirects.sh
+      - name: Check internal links and images
+        run: bash check-links.sh
       - run: mkdir ./public
       - run: cp -R static/* ./public/
       - run: mv ./en/book/* ./public/en/

AGENTS.md

@@ -0,0 +1,107 @@
+# AGENTS.md
+
+Guidance for working on this repo (an mdBook site deployed to help.loomio.com via GitHub Pages).
+
+## Commit hygiene
+
+- No self-promotion or marketing in commits: don't add "Co-Authored-By"
+  lines or similar credit/attribution for AI tooling to commit messages.
+- If documenting AI-agent guidance in a file, use the standard filename
+  `AGENTS.md` (this file) rather than tool-specific names like `CLAUDE.md`.
+
+## Deploy structure — the "/en nesting" footgun
+
+`.github/workflows/gh-pages.yml` builds the book and assembles the deployed
+site like this:
+
+```
+mdbook build en                  # -> en/book/*  (real content, e.g. en/book/user_manual/foo/index.html)
+cp -R static/* ./public/         # -> public/*   (top-level static files, e.g. favicon, robots.txt)
+mv ./en/book/* ./public/en/      # -> public/en/*  (nests ALL book content one level under /en)
+```
+
+So on disk, book content lives at `en/book/user_manual/...` (no `en/`
+segment), but on the live site it's served at `/en/user_manual/...`. Two
+consequences that have caused real bugs:
+
+1. **Redirect `from` keys in `en/book.toml` must NOT start with `/en/`.**
+   mdBook writes a redirect stub file literally at `book_dir/<from>`. If
+   `from` already starts with `/en/`, deploy nests it *again*, producing
+   `/en/en/...` — a path nothing ever requests, so the redirect silently
+   404s. Correct form: `"/user_manual/groups/foo/index.html" = "/en/user_manual/bar/index.html"`
+   — no `/en` on the left (from), full `/en/...` path on the right (to,
+   since that's the real browser-facing URL used in the meta-refresh/canonical tag).
+2. **Internal markdown links must include the `/en/` prefix**, e.g.
+   `/en/user_manual/groups/settings/`, not `/user_manual/groups/settings/`.
+   A link missing `/en/` can *look* fine when checked against the local
+   `en/book/` directory (the relative path happens to exist there), but on
+   the live site paths without `/en/` only resolve against top-level
+   `static/*` content — so it 404s in production despite passing a naive
+   local check. This exact bug shipped and was only caught by crawling the
+   live site (see below).
+
+Any time you touch `book.toml` redirects or add/edit internal links, keep
+this nesting model in mind — it's the single most common source of "works
+locally, 404s live" bugs in this repo.
+
+## Link style convention
+
+Internal links to pages use a **trailing slash** (`/en/user_manual/groups/settings/`),
+not `/index.html` (`/en/user_manual/groups/settings/index.html`) and not a
+bare path with neither (`/en/user_manual/groups/settings`). All three
+technically resolve on GitHub Pages, but the bare form costs an extra
+301 round-trip (GH Pages redirects `/foo` → `/foo/` before serving
+`index.html`), and it's also the shape that's easiest to typo into a
+missing-`/en/`-prefix bug. Prefer trailing slash when writing or editing
+links in `en/src/**/*.md`.
+
+## Checking scripts
+
+Two scripts validate the built book before deploy, and are wired into
+`.github/workflows/gh-pages.yml` right after `mdbook build en`:
+
+- `check-redirects.sh` — for every `[output.html.redirect]` entry in
+  `en/book.toml`, verifies the target page actually exists in the built
+  book, and flags any `from` key that starts with `/en/` (the double-nest
+  bug above).
+- `check-links.sh` — walks every built HTML page, extracts every `<a href>`
+  and `<img src>`, and verifies the target resolves — correctly modeling
+  the `/en` nesting split between `en/book/` and `static/`, and accepting
+  GitHub Pages' directory-index resolution (`/foo/` or `/foo/index.html`
+  both count as valid, matching real server behavior).
+
+Run both locally after `mdbook build en` before pushing changes that touch
+redirects or links:
+
+```
+mdbook build en
+./check-redirects.sh
+./check-links.sh
+```
+
+Neither script catches everything, though — they only validate against the
+locally built tree. The redirect-nesting bug above shipped once already
+despite `check-redirects.sh` passing, because the script checked "does the
+target file exist" but not "does the `from` path actually reach that file
+once deployed." If you suspect something is broken only in production,
+crawl the live site directly:
+
+```bash
+curl -s https://help.loomio.com/sitemap.xml | grep -oE '<loc>[^<]+</loc>' | sed -E 's/<\/?loc>//g'
+# then fetch each page, extract internal <a>/<img> targets, HEAD each one
+```
+
+This is slow (real HTTP round-trips) but is ground truth — it's what
+actually caught both the redirect-nesting bug and three markdown links
+that were missing their `/en/` prefix.
+
+## mdBook behavior notes
+
+- mdBook auto-rewrites `.md` links (even absolute ones like
+  `/en/user_manual/foo/bar.md`) to `.html` at build time — this is normal
+  and expected, don't "fix" these.
+- `SUMMARY.md` is the source of truth for what actually gets built into a
+  page. A `.md` file can exist under `en/src/` with real content and still
+  never be built into HTML if it isn't referenced from `SUMMARY.md` — this
+  caused an orphaned page (`engaging_with_discussions`) whose old redirect
+  target silently never existed.

check-links.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# Verify every internal <a href> and <img src> in the built book resolves to
+# a real file. Run after `mdbook build en`.
+set -euo pipefail
+
+BOOK_DIR="en/book"
+STATIC_DIR="static"
+
+if [ ! -d "$BOOK_DIR" ]; then
+  echo "error: $BOOK_DIR not found. Run 'mdbook build en' first." >&2
+  exit 1
+fi
+
+python3 - "$BOOK_DIR" "$STATIC_DIR" <<'PYEOF'
+import sys, os, re
+from html.parser import HTMLParser
+from urllib.parse import urlsplit
+
+book_dir = sys.argv[1]
+static_dir = sys.argv[2]
+
+class LinkParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.links = []  # (attr, value)
+
+    def handle_starttag(self, tag, attrs):
+        attrs = dict(attrs)
+        if tag == "a" and attrs.get("href"):
+            self.links.append(("href", attrs["href"]))
+        elif tag == "img" and attrs.get("src"):
+            self.links.append(("src", attrs["src"]))
+
+def is_external(url):
+    return (
+        url.startswith("http://") or url.startswith("https://")
+        or url.startswith("mailto:") or url.startswith("tel:")
+        or url.startswith("//")
+    )
+
+failures = 0
+checked = 0
+
+for root, dirs, files in os.walk(book_dir):
+    for fname in files:
+        if not fname.endswith(".html"):
+            continue
+        fpath = os.path.join(root, fname)
+        with open(fpath, encoding="utf-8", errors="replace") as f:
+            content = f.read()
+
+        parser = LinkParser()
+        parser.feed(content)
+
+        for attr, raw_url in parser.links:
+            url = raw_url.strip()
+            if not url or url.startswith("#") or is_external(url):
+                continue
+
+            split = urlsplit(url)
+            path_part = split.path
+            if not path_part:
+                # pure fragment or query, already excluded above but be safe
+                continue
+
+            checked += 1
+
+            # GitHub Pages resolves extensionless/directory paths to
+            # "<path>/index.html" (redirecting "/foo" -> "/foo/" first), so
+            # accept that form too before calling anything broken.
+            def exists(base, rel):
+                target = os.path.join(base, rel)
+                return os.path.isfile(target) or os.path.isfile(os.path.join(target, "index.html")), target
+
+            if path_part.startswith("/"):
+                # Absolute paths are site-root-relative. The deploy step
+                # (see gh-pages.yml) does:
+                #   cp -R static/* public/          (static/foo -> /foo)
+                #   mv en/book/* public/en/          (book content -> /en/foo)
+                # so a path starting with "/en/" resolves against book_dir
+                # (or static/en/*, which lands in the same public/en/ tree),
+                # while anything WITHOUT the "/en/" prefix only exists if
+                # static/ has a matching top-level file/dir - it is never
+                # served by the book, even though the same relative path
+                # may coincidentally exist inside book_dir on disk.
+                rel = path_part.lstrip("/")
+                if rel == "en" or rel.startswith("en/"):
+                    rel = rel[len("en"):].lstrip("/")
+                    resolved, target = exists(book_dir, rel)
+                    if not resolved:
+                        resolved, target = exists(static_dir, path_part.lstrip("/"))
+                else:
+                    resolved, target = exists(static_dir, rel)
+                    if not resolved:
+                        target = f"{static_dir}/{rel} (note: path is missing a leading /en/ segment)"
+            else:
+                target = os.path.normpath(os.path.join(root, path_part))
+                resolved = os.path.isfile(target) or os.path.isfile(os.path.join(target, "index.html"))
+
+            if not resolved:
+                rel_source = os.path.relpath(fpath, book_dir)
+                print(f'BROKEN {attr}: "{raw_url}" in {rel_source} (no file at {target})')
+                failures += 1
+
+print()
+print(f"checked {checked} links/images, {failures} broken")
+sys.exit(1 if failures else 0)
+PYEOF

check-redirects.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Verify every redirect target in en/book.toml points at a file that
+# actually exists in the built book. Run after `mdbook build en`.
+set -euo pipefail
+
+BOOK_DIR="en/book"
+TOML="en/book.toml"
+
+if [ ! -d "$BOOK_DIR" ]; then
+  echo "error: $BOOK_DIR not found. Run 'mdbook build en' first." >&2
+  exit 1
+fi
+
+failures=0
+count=0
+
+# Pull out each "from" = "to" line inside [output.html.redirect]
+while IFS= read -r line; do
+  from=$(echo "$line" | sed -E 's/^"([^"]+)".*/\1/')
+  to=$(echo "$line" | sed -E 's/^[^=]+= *"([^"]+)".*/\1/')
+
+  count=$((count + 1))
+
+  # The gh-pages workflow does `mv en/book/* public/en/`, so every file
+  # mdbook writes under book_dir ends up nested one level deeper under
+  # "/en" on the live site. A "from" key that itself starts with "/en/"
+  # would therefore double-nest (mdbook writes the stub to
+  # book_dir/en/user_manual/... which deploys to /en/en/user_manual/...)
+  # and never match the real broken URL. "from" keys must NOT start with
+  # "/en/".
+  if [[ "$from" == /en/* ]]; then
+    echo "BROKEN: \"$from\" -> \"$to\" (from-path starts with /en/, will double-nest to /en$from on deploy)"
+    failures=$((failures + 1))
+    continue
+  fi
+
+  # Redirect targets are site-absolute paths (e.g. "/en/user_manual/foo.html"
+  # or "/guides/foo.html"); the book is deployed as en/book/* -> public/en/*,
+  # so strip a leading "/en" to get the book-relative path.
+  target="${to#/}"
+  target="${target#en/}"
+  resolved="$BOOK_DIR/$target"
+
+  if [ ! -f "$resolved" ]; then
+    echo "BROKEN: \"$from\" -> \"$to\" (no file at $resolved)"
+    failures=$((failures + 1))
+    continue
+  fi
+done < <(grep -E '^"[^"]+"\s*=\s*"[^"]+"' "$TOML")
+
+echo ""
+echo "checked $count redirects, $failures broken"
+[ "$failures" -eq 0 ]

en/book.toml

@@ -24,21 +24,21 @@ site-url = "/en/user_manual/"
 "/user_manual/threads/invite_only/index.html" = "/en/user_manual/discussions/direct_discussions/index.html"
 "/user_manual/threads/examples/index.html" = "/en/user_manual/discussions/examples/index.html"
 "/user_manual/threads/templates/index.html" = "/en/user_manual/discussions/templates/index.html"
-"/user_manual/threads/engaging_with_threads/index.html" = "/en/user_manual/discussions/engaging_with_discussions/index.html"
+"/user_manual/threads/engaging_with_threads/index.html" = "/en/user_manual/discussions/using_discussions/index.html"
 "/user_manual/getting_started/index.html" = "/en/user_manual/overview/index.html"
 "/user_manual/getting_started/orientation.html" = "/en/user_manual/overview/orientation.html"
 "/user_manual/getting_started/write-a-comment.html"  = "/en/user_manual/overview/how-to-participate.html"
 "/user_manual/groups/intro_to_groups/index.html" = "/en/user_manual/groups/index.html"
 "/user_manual/getting_started/decisions/index.html" = "/en/user_manual/making_decisions/index.html"
-"/guides/advice_process/index.html" = "/en/user_manual/making_decisions/advice_process.html"
-"/guides/consent_process/index.html" = "/en/user_manual/making_decisions/consent_process.html"
-"/guides/consensus_process/index.html" = "/en/user_manual/making_decisions/consensus_process.html"
 "/user_manual/polls/decisions/index.html" = "/en/user_manual/making_decisions/simple_decision_process.html"
-"/user_manual/groups/membership/index.html" = "/en/user_manual/groups/inviting-people/index.html"
+"/user_manual/groups/membership/index.html" = "/en/user_manual/groups/inviting_people/index.html"
 "/user_manual/groups/membership/management.html" = "/en/user_manual/groups/member_management/index.html"
 "/user_manual/groups/membership/delegated_voters.html" = "/en/user_manual/groups/delegated_voters/index.html"
 "/user_manual/groups/thread_management/index.html" = "/en/user_manual/discussions/discussion_management/index.html"
 "/user_manual/groups/tags/index.html" = "/en/user_manual/discussions/tags/index.html"
-"/user_manual/groups/deleting_archiving/index.html" = "/en/user_manual/deleting_your_group/index.html"
+"/user_manual/groups/deleting_archiving/index.html" = "/en/user_manual/groups/deleting_your_group/index.html"
+"/guides/advice_process/index.html" = "/en/user_manual/making_decisions/advice_process.html"
+"/guides/consent_process/index.html" = "/en/user_manual/making_decisions/consent_process.html"
+"/guides/consensus_process/index.html" = "/en/user_manual/making_decisions/consensus_process.html"
 # "privacy" = "/en/policy/privacy"
 # key-concepts  -> overview

en/src/guides/facilitators_guide/commencing/index.md

@@ -41,7 +41,7 @@ On Loomio
 
 * The group description fields and discussion context box are the main space to put a “welcome message” for people arriving into the space.
 * Take a tour of the Loomio space, tweak things to make yourself comfortable (like [notification settings](/en/user_manual/users/email_settings/) and your [profile photo](/en/user_manual/users/user_profile/).
-* See information how you like using [different thread views and options](/en/user_manual/users/navigation) like Recent, Unread, Mute, and Star. Make yourself at home.
+* See information how you like using different thread views and options like Recent, Unread, Mute, and Star. Make yourself at home.
 
 
 ## Who’s in the Room

en/src/guides/facilitators_guide/concluding/index.md

@@ -16,7 +16,7 @@ Sometimes the answers to these questions are very concrete, such as action point
 
 On Loomio
 
-* [Outcomes](/en/user_manual/polls/outcomes) are a very important tool. A proposal ending is not quite the end: there’s a need to sum up conclusively. That's what the outcome feature is for.
+* [Outcomes](/en/user_manual/polls/outcomes/) are a very important tool. A proposal ending is not quite the end: there’s a need to sum up conclusively. That's what the outcome feature is for.
 * Many Loomio discussions come to a natural end without even using proposals or publishing outcomes. These discussions still provide a lot of value, and it can be helpful to update the context box with an outcome summary for later reference.
 * If specific people have action points, you can @mention their names and they will be notified.
 
@@ -67,6 +67,6 @@ Participants often look to the leader or facilitator for confirmation of when it
 On Loomio
 
 * The clearest indication of conclusion on Loomio is publishing a decision outcome.
-* Some groups use the [close thread](/en/user_manual/threads/thread_admin#close-thread) feature to archive discussions and reduce clutter.
+* Some groups use the [close thread](/en/user_manual/threads/thread_admin/#close-thread) feature to archive discussions and reduce clutter.
 * Deactivating a group is the strongest possible “closure” move. No one can say anything else after that.
 * Since Loomio groups can remain while group activity goes up and down, it can be useful to recognize milestones like the conclusion of a particular phase, even if the group will reactivate in the future.

en/src/guides/facilitators_guide/preparation/index.md

@@ -14,7 +14,7 @@ Clarification of purpose is one of the highest value offerings of a skilled faci
 
 On Loomio
 
-* The app offers space for explication of purpose, such as the [group description](/en/user_manual/groups/starting_a_group#group-description) and [discussion context](/en/user_manual/threads/engaging_with_threads/#thread-context) fields.
+* The app offers space for explication of purpose, such as the [group description](/en/user_manual/groups/starting_a_group/#group-description) and [discussion context](/en/user_manual/threads/engaging_with_threads/#thread-context) fields.
 * A Loomio discussion *about* purpose is a great place to start with your group, if it's not already clear.
 * Our analytics (stats about how people use the software) show that groups with a clear shared purpose are more successful.
 * [Customer stories and case studies](https://blog.loomio.com/?utm_campaign=facilitators_guide_help&utm_term=help) we've collected emphasise the importance of setting a collective purpose.
@@ -29,8 +29,8 @@ In offline spaces, literally rearranging the furniture is a habit that helps fac
 On Loomio
 
 * Inviting people into a new digital space specifically for decision making is powerful — there’s a “threshold crossing” experience making it as distinct from other online spaces (which might be for socialising or other functions).
-* [Customising your group photo](/en/user_manual/groups/starting_a_group#upload-a-group-photo) is a prime opportunity to craft the feeling of the space.
-* The group description is a main piece of “furniture” on the group page, and [you can customise it](/en/user_manual/groups/starting_a_group#group-description) to suit.
+* [Customising your group photo](/en/user_manual/groups/starting_a_group/#upload-a-group-photo) is a prime opportunity to craft the feeling of the space.
+* The group description is a main piece of “furniture” on the group page, and [you can customise it](/en/user_manual/groups/starting_a_group/#group-description) to suit.
 
 
 ## Supplies, Tools, Materials
@@ -58,7 +58,7 @@ On Loomio
 ![](../collaboration-process.png)
 
 * Skilled users are already adapting Loomio for various experience designs — such as a multi-step consultation processes, signing off documents, etc. Each job, when facilitated effectively, takes a certain repeatable shape.
-* Online collaboration design doesn't have to reinvent the wheel. Trust what you know works, and translate it. Many tried and tested offline processes can be adapted to the online space (ex: the [Advice Process](/en/guides/advice_process)).
+* Online collaboration design doesn't have to reinvent the wheel. Trust what you know works, and translate it. Many tried and tested offline processes can be adapted to the online space (ex: the [Advice Process](/en/guides/advice_process/)).
 * [Case studies](https://blog.loomio.com/?utm_campaign=facilitators_guide_help&utm_term=help) of thoughtfully designed processes could be used as “recipes” — if you're not sure what design to use, start by seeing what others have tried.