Skip to content

Site review: correct page text; keep app text and bad apps from breaking the site - #32

Merged
IvanHCenalmor merged 1 commit into
mainfrom
site/review-fixes
Nov 17, 2026
Merged

IvanHCenalmor merged 1 commit into
mainfrom
site/review-fixes

Conversation

@IvanHCenalmor

Copy link
Copy Markdown
Contributor

Fixes what a full review of the site found in this repository. Fixes that belong to other repositories go there (the template's in CellMigrationLab/LabConstrictor#59).

Page text

  • How it works
    • Template updates are now an optional step after the first release. The template says to set them up then; the page said before initialising.
    • Code cells can be hidden; whether they are hidden or shown by default is your choice.
    • A licence is recommended, not required. The Submit page says the same.
  • Demo
    • The QuPath extension is no longer called a prototype.
    • "How the connection works" names napari, Fiji and QuPath.
  • Use page and Docs home
    • The demo covers Windows and macOS.
    • The napari picture is no longer called a prototype.
  • Menus: guide titles in the sidebar, pager and Docs list are plain text. They showed the backticks of "the labconstrictor-app.yaml file".
  • 404 page: it now has a title ("Page not found") and links to Home, the App Centre and Docs. It had an empty title and nothing else.
  • App Centre: it gets "Edit this page on GitHub", as DESIGN.md asks.
  • Footer: "Cite LabConstrictor" goes to the home page's #cite, not index.html#cite.

App text and pictures (written by app authors)

  • No links from app text. Markdown link syntax in an app's summary became a GitHub link after escaping. Inside the App Centre card's data-search attribute it broke the markup. esc now also encodes [ and ], and link decoration skips code.
  • A broken picture leaves out only that app. Pictures are fully decoded when they are downloaded, so one that is too large, or broken after a valid header, is caught there instead of stopping the whole build later.
  • File paths are quoted when they are downloaded, so an image path with a space no longer crashes the fetch.
  • App text no longer stops the publish:
    • two apps with the same summary no longer fail check_design;
    • short text such as "> no longer counts as unescaped in check_site.
  • Windows: check_design names pages the same on every system, which removes the Windows-only false alarm on template-synchronization.
  • Submissions are checked against the addresses and names that listed apps already use. Before, a duplicate passed the check but was then left out of the site.

Workflows

  • publish.yml
    • Each job gets only the permissions it needs; the build, which also runs on pull requests, can only read.
    • The "apps left out" issue is opened by its own job.
  • validate-submission.yml
    • The check, which parses the submitted manifest and pictures, runs with a read-only token. Commenting and opening the pull request are separate jobs.
    • One run per issue at a time.
    • A pull request opened with the workflow's token does not start the site build. Its body now says to close and reopen it before merging. Making that automatic would need a separate token as a secret, which is the maintainers' call.

Smaller fixes

  • List rewriting (gfm.lists): a heading, rule, quote, code block or HTML right after a list item, and a list of another kind (numbers after bullets), end the list as on GitHub.
  • App pages: install steps are read at the indentation gfm.lists writes, and code keeps its line breaks. The output of the current install guide is unchanged.
  • How it works: "Skip to content" no longer jumps back to step 1. DESIGN.md now describes what the page does on narrow screens: one step at a time.
  • Demo:
    • the address follows the part when the installer opens the app, so a reload stays there;
    • the double-click selection is drawn from the state, so it clears on Windows too.

Checks

  • 260 unit tests pass, including the new tests/test_app_text_safety.py and new cases in test_gfm, test_catalogue and test_get.
  • A full local build passes, with check_site and check_design reporting 0 problems.
  • Comparing every built page with main shows only the changes above. App pages differ only in the footer link.
  • Not tried in a browser: the How it works and demo script changes. They pass node --check and the JS rule tests.

🤖 Generated with Claude Code

…ing the site

Page text (hand-written here):
- How it works: template updates are optional and come after the first release
  (as the template says); code cells can be hidden or shown by default; a licence
  is recommended, not required (also on Submit).
- Demo: the QuPath extension is no longer called a prototype; the connection
  steps name all three programs. Use page and Docs home: the demo covers
  Windows and macOS; the napari picture is no longer called a prototype.
- Guide titles in the sidebar, pager and Docs list are plain text (no backticks).
- A 404 page with a title and links to Home, the App Centre and Docs.
- The App Centre gets "Edit this page on GitHub"; the footer's Cite link goes to #cite.

Untrusted app text and pictures:
- esc() also encodes [ and ], so Markdown link syntax in an app's text is shown as
  written and never becomes a link (it broke the card's data-search attribute).
  decorate_links leaves code alone.
- Pictures are fully decoded when they are downloaded, so one too large or broken
  leaves out that app instead of stopping the site build; file paths are quoted.
- Two apps with the same summary, or short text such as '">', no longer stop the
  publish in check_design / check_site. check_design names pages the same on Windows.
- A submission is checked against the addresses and names listed apps already use.

Workflows:
- publish.yml: each job gets only the permissions it needs; the build (which also
  runs on pull requests) can only read; the left-out-apps issue is its own job.
- validate-submission.yml: the check runs with a read-only token; commenting and
  opening the pull request are separate jobs; one run per issue at a time; the
  pull request says how to start the site build on it.

Smaller fixes:
- gfm.lists: a heading, rule, quote, code block or HTML right after a list item,
  and a list of another kind, end the list as on GitHub.
- App-page install steps are read at the indentation gfm.lists writes; code keeps its lines.
- How it works: "Skip to content" no longer jumps to step 1; DESIGN.md matches the
  one-step-at-a-time page on narrow screens.
- Demo: the address follows the part when the installer opens the app; the
  double-click selection is drawn from the state for Windows and macOS alike.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@IvanHCenalmor
IvanHCenalmor merged commit 52d16eb into main Nov 17, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant