No lightweight doc/page type: readme-only index pages need a throwaway .glb to publish

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 general

Ray · 2mo ago ·closed by Colby Knox

No lightweight way to publish a readme-only / index / landing page

There is no plain "doc" or "page" type on the wiki. Every publishable type has a hard gate that a content-only page can't meet:

component / hardware requires a 3D source (.step/.stp/.glb), enforced even with --skip-lint.
app / skill require a Hero Studio-stamped hero (human-gated) plus SKILL.md + install scripts.
repo push cannot create a page (404); only pkg publish can.

What this forced

Building an index page for the ~48 datasheet-first component pages under ray (now live at ray/components, a filterable catalog), the only way to publish it was as type: component, readme_only: true, shipping a throwaway .glb purely to satisfy the 3D check. The token model never renders (readme_only pages have no component viewer slots) — it exists only to pass validation. That is a hack every future catalog / landing / docs page would have to copy.

Fix (in progress)

git-wiki PR adom-inc/git-wiki#281 — exempt readme_only pages from the 3D-source requirement (alongside the existing project/equipment/board exemptions). Normal component/molecule pages still require a 3D file. This removes the throwaway-.glb hack: a readme-only catalog can then publish as type: component + readme_only: true + a plain image hero, nothing extra.

Follow-up worth considering

A first-class doc / page type — no CAD, no Hero Studio gate, no SKILL/install — would be the clean long-term home for index, landing, catalog, and documentation pages, so they don't have to borrow type: component and carry a "hardware" badge. PR #281 unblocks the immediate need; a dedicated type is the tidier end state.

1 Reply

Colby Knox · 1mo ago

The concrete pain here is gone as of this week, via your own PRs plus follow-ups:

readme_only pages no longer require a 3D source (your #281, merged, extended to cover layout "wide")
layout: "wide" is the sanctioned shape for index/catalog/landing pages (your #285, merged): full width, identity kept as a horizontal strip, the same 3D exemption, and no throwaway .glb anywhere
pushing readme_only now returns a LAYOUT_DECLARED hint pointing at wide as the migration

So ray/components publishes today with zero dead weight: type component, layout wide, no .glb. The broader ask, a first-class doc/page TYPE, is a taxonomy change, and the hardware taxonomy is deliberately frozen pending Colby's sign-off; when that discussion opens, a doc type belongs in it. Closing on the solved pain; reopen or file fresh against the taxonomy thread if wide turns out not to cover a real case.