Skip to content

Repository navigation

Fix five ports' docs builds and tidy the port landing page - #296

Merged
tony merged 6 commits into
mainfrom
fix/badges-and-clojure-leg
Nov 10, 2026
Merged

Fix five ports' docs builds and tidy the port landing page#296
tony merged 6 commits into
mainfrom
fix/badges-and-clojure-leg

Conversation

@tony

@tony tony commented Nov 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Fix the Lua, Elixir, Kotlin and Scala docs builds, which stop on their README version badges at 8245169.
  • Add LuaRocks, Hex and Maven Central to the version badges scripts/lib/badges.mjs renders from registry.json (Render guide badges locally instead of hotlinking shields #288 mapped gem, crates, npm, nuget, PowerShell Gallery and PyPI only).
  • Fix the Clojure leg of libtmux-java's docs build, which has no Java checkout for gen-tmux-usage.mjs.
  • Fix the doubled "APIs used" list on the OCaml landing page: its quickstart and its typed-graph capability drew two panels with one id.
  • Move the per-example CI sentence on port landing pages into one footer, and remove the "All versions and install instructions" link, which redirected back to the same page.

Changes

  • scripts/lib/badges.mjs: each version service carries its shields default label and the number of path segments before the package (a LuaRocks user, a Maven group). An unknown service still throws.

  • scripts/build-site.sh: for the clojure port, export LIBTMUX_DOCS_CHECKOUT_JAVA from LIBTMUX_DOCS_CHECKOUT_CLOJURE unless it is already set. Clojure lives in the Java repository, so the two checkouts are the same directory.

  • site/test/port-guide-badges.test.ts: one case per new service, plus two that must still throw (hexpm/dt, a short maven-central path).

  • site/src/components/CoreShowcase.astro: leave the quickstart's capability out of the port table entries, so each capability id is one panel; drop the per-example CI paragraph.

  • site/src/pages/index.astro: list each showcase program and its CI workflow in a muted footer; remove the port-root link (/en/<port>/ redirects to /en/<port>/latest/).

  • site/test/core-capabilities.test.ts, site/test/port-landing-page.test.ts: unique panel ids for every port (fails for ocaml without the fix), the footer, and no port-root link.

Failures this fixes

  • libtmux-lua#95 run 42714080219: lua: unsupported badge https://img.shields.io/luarocks/v/tony/libtmux?label=libtmux
  • libtmux-elixir#70 run 42714567836: elixir: unsupported badge https://img.shields.io/hexpm/v/libtmux?label=libtmux
  • libtmux-java#147 run 42714401041: kotlin and scala stop on their maven-central badges; clojure stops with java: no checkout at /home/runner/work/libtmux/libtmux-java; set LIBTMUX_DOCS_CHECKOUT_JAVA

Those three caller PRs were held out of the wave at 8245169; they join the next one with this fix.

Test plan

  • The new badge cases fail against badges.mjs on main and pass with the change; the unknown-service cases still throw
  • site/test/stage-port-docs.test.ts passes
  • Every shields URL in the lua, elixir, kotlin, scala, java and clojure READMEs maps through badgeSpec against site/src/data/registry.json
  • gen-tmux-usage.mjs --ports clojure completes with an empty HOME and only the clojure checkout set
  • Every port's showcase panel ids are unique (the case fails for ocaml before the fix); the landing footer renders and the port-root link is gone
  • Full CI
  • The clojure leg of a libtmux-java docs build pinned to this change

tony added 5 commits November 9, 2026 17:35
@tony
badges(fix[services]) Render LuaRocks, Hex and Maven Central version …
d1d44a8 
…badges

why: The lua, elixir, kotlin and scala docs builds failed with
"unsupported badge" because their READMEs carry luarocks, hexpm and
maven-central shields, which badges.mjs had no mapping for. The Java
README's Maven Central badges would have failed the same way.

what:
- Replace the version-service label map with entries holding shields'
  default label and the number of qualifier segments before the package
  (LuaRocks user, Maven group).
- Add luarocks (luarocks), hexpm (hex) and maven-central (maven-central),
  resolved through registryVersion, which already falls back to the port
  entry's own version when it lists no packages.
- Test each service against a port entry without packages, with and
  without a label query, and that an unmapped path on these services
  still throws.
@tony
build-site(fix[clojure]) Point the Java core checkout at the clojure …
16b3c3f 
…checkout

why: The clojure leg of the Java docs build failed in gen-tmux-usage with
"java: no checkout at .../libtmux-java". port-docs.yml exports only
LIBTMUX_DOCS_CHECKOUT_CLOJURE, but gen-tmux-usage also derives the Java
core the wrapper stands on and looks for Java at its default path, which a
clean runner lacks. Clojure lives in the Java repository, so the two
checkouts are the same directory.

what:
- Export LIBTMUX_DOCS_CHECKOUT_JAVA from LIBTMUX_DOCS_CHECKOUT_CLOJURE
  before gen-tmux-usage runs for the clojure port, keeping an explicit
  Java override if one is set.
@tony
CoreShowcase(fix[panels]) Draw each capability once
696e8e1 
why: OCaml's capability table has a typed-graph entry, and the quickstart
panel carries the same capability. Both panels got
data-capability-panel="typed-graph". The script selects panels by id, so
both showed in one grid cell and the "APIs used" list drew twice.
what:
- Leave the quickstart's capability out of the table programs when a
  quickstart exists; the menu and the APIs map are built from the one list
- Add a test that every port's panel ids are unique and match the menu
@tony
landing(refactor[ci-footer]) Move the example CI note to the page footer
de459bf 
why: The sentence under every example named the workflow, directory and
command that run it. Readers choosing an example do not need that; the
capability menu already shows each tmux version. The maintainer asked for
it at the bottom of the page.
what:
- Drop the per-example source paragraph, its tmux chip and its styles
  from CoreShowcase
- Add a muted footer at the end of the port landing page with one line
  per example: the linked program file and the workflow that runs it
- Leave the command out, as it does not fit on one line
- Assert the footer and the removed paragraph in the showcase and
  landing page tests
@tony
landing(fix[versions-link]) Remove the self-referencing versions link
e07bff9 
why: /en/<port>/ has redirected to /en/<port>/latest/ since September, so
"All <port> versions and install instructions" sent readers back to the
page they were on. It dates from when install lived at the port root.
The version switcher is the way to change versions.
what:
- Remove the link and its withPortRoot import from the port landing page
- Assert that no link to the port root remains
@tony tony changed the title Fix the Lua, Elixir, Kotlin, Scala and Clojure docs builds Fix five ports' docs builds and tidy the port landing page Nov 10, 2026
@tony
landing(fix[ci-footer]) Wrap long paths in the example footer
0149aad 
why: The footer's file and workflow paths do not break, so on a 280px
screen the rs landing page scrolls sideways (the header check measures
scrollWidth 283 against a 280px viewport). The paragraph it replaced
wrapped its code with overflow-wrap: anywhere.
what:
- Give the footer wrap-anywhere, which its code elements inherit
This was referenced Nov 10, 2026
Open
Open
Draft
@tony
tony deployed to docs-preview November 10, 2026 05:27 — with GitHub Actions Active
@tony
tony merged commit 30af469 into main Nov 10, 2026
3 checks passed
@tony
tony requested a deployment to docs-preview-cleanup November 10, 2026 06:01 — with GitHub Actions In progress

This branch is being deployed

1 in progress and 1 active deployments
docs-preview-cleanup — 0149aad1 Deployed Nov 10, 2026 by tony via cleanup #230
docs-preview — 0149aad1 Deployed Nov 10, 2026 by tony via publish-preview / publish #1379
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tony