Deep-link readme.html sections: forward the page URL hash to the readme iframe + a readme-scroll-to protocol

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity

Closed feature request

Ray · 2mo ago ·closed by Colby Knox

The gap

readme.html renders in a sandboxed iframe, so any section ids live inside the iframe. A hash on the page URL (wiki.adom.inc/<owner>/<slug>#<section>) therefore never scrolls to the section, because the wiki does not forward the parent hash down to the readme iframe. Readme authors can add ids and anchor links, but they cannot make the pretty page URL deep-link to a section from the readme side. This needs platform support.

Verified (on adom/component-widgets, an HTML readme)

Added ids + hover-reveal anchor links to every section (pinout, moleculize, etc.).
wiki.adom.inc/adom/component-widgets#moleculize → stays at the top, does not jump.
wiki.adom.inc/readme/adom/app/component-widgets?variant=public#moleculize → jumps correctly to the section (the ids work fine within the readme document; only the parent-to-iframe hop is missing). This raw-endpoint URL is the only working deep link today, but it drops the wiki page chrome and is not the shareable page URL.

Ask

When the page URL carries a hash, deep-link the readme section. Two coordination points, because the readme iframe is sized to its full content via the existing readme-height protocol (so the readme cannot scroll itself):

Forward the hash down. On load and on hashchange, pass the page URL's #<id> to the readme (append to the iframe src, or postMessage({type:'readme-hash', hash})).
Scroll the page up. The readme finds the target, and posts its position so the parent scrolls the page to it, e.g. a new sibling to readme-height / readme-lightbox:
```
parent.postMessage({ type: 'readme-scroll-to', top: el.getBoundingClientRect().top + window.scrollY }, '*')
```
The wiki scrolls to iframeOffsetTop + top.

That makes wiki.adom.inc/<owner>/<slug>#<section> land on the section for any HTML readme (component pages, docs, guides). Natural home for the protocol doc is docs/readme-sandbox.md (the readme-iframe protocols, adom/wiki #52), alongside readme-height and readme-lightbox.

Why it matters

Component pages are getting rich multi-section readmes (a page of widgets, a datasheet-plus-CAD hub). Being able to hand someone a link straight to the pinout, or the board-to-molecule widget, is the difference between "go find it" and "here it is." Related: the wiki-readme-html skill documents the sandbox and its current protocols.

1 Reply

Colby Knox · 2mo ago

Shipped and live on prod. Thanks Ray, this was a clean, well-scoped report, and your "verified on adom/component-widgets" breakdown (page URL hash does nothing vs the raw /readme/... endpoint jumping correctly) pointed straight at the missing parent-to-iframe hop.

Implemented exactly the two coordination points you laid out, as a readme-scroll-to protocol sitting next to readme-height and readme-lightbox:

Forward the hash down. The page (static/app.js) posts { type: "readme-hash", hash } into the frame on the frame's load and on every hashchange.
Scroll the page up. A helper finds the target (getElementById, falling back to [name=]) and posts { type: "readme-scroll-to", top: el.getBoundingClientRect().top + scrollY }; the parent scrolls the whole page to frameOffsetTop + top (with a small offset so the heading clears the top edge). Same source-identity check and numeric clamp as the sibling protocols.

One thing beyond the ask: rather than require every readme author to add the frame-side listener, the wiki injects that helper into every readme frame automatically, so any existing HTML readme whose sections carry ids is deep-linkable with zero author change. Sandbox-safe (no network, no storage, only parent.postMessage).

So wiki.adom.inc/<owner>/<slug>#<section> now lands on the section for any HTML readme. I verified it end to end in a headless browser against staging: a page that sits at scrollY: 0 with no hash scrolled to ~1485px when the hash was set, via the full round-trip.

Protocol is documented in docs/readme-sandbox.md next to readme-height/readme-lightbox. Give your component-widgets sections their ids (you already did) and the shareable page URL deep-links now. Closing as done.