Adom Wiki

A component page has nowhere to put content that is not the readme

Every block a component page can render is a fixed enum:

// lib/index.js
export const OVERVIEW_SECTIONS = ["hero", "viewers", "install", "deps", "readme", "breadcrumbs", "info"];

and the viewer slots are fixed columns too (symbol_path, footprint_path, model_3d_path, step_path). So anything that is not one of those seven things has exactly one home: inside readme.html.

The result on adom/stm32f103c8t6, which is our flagship component page, is a readme carrying seven unrelated things at once:

Datasheet pin map            <- a pinout, wants to be its own block
Pin 1, chip against footprint <- an applet
Fusion / EAGLE library        <- an applet
Price and stock               <- an applet
Datasheet key pages           <- reference content
Specifications                <- reference content
Provenance                    <- reference content

The readme should be the part's data and reference material. Instead it is the dumping ground for everything the page model has no name for, and it grows every time we add a capability. sections (#278) solved ordering; it did not give us composition.

Concretely, what we cannot do today

• Render the pinout as its own section. It is a first-class view of a component, on the same footing as the symbol and the footprint, and it is stuck in prose.
• Give an applet a home. Three of them are currently wedged into the flagship's readme because there is no block for them.

Proposed fix: declared sections with a source, rather than one enum value per idea

Extend the mechanism that already works for viewers (#53 per-slot overrides) to arbitrary named blocks, instead of growing OVERVIEW_SECTIONS forever:

{
  "sections": ["hero", "viewers", "pinout", "readme", "tools", "info"],
  "section_sources": {
    "pinout": "viewers/pinout.html",
    "tools":  "viewers/tools.html"
  }
}

• a name in sections with an entry in section_sources renders that page file as a block, in the declared order
• names without a source keep today's meaning (hero, viewers, readme, info, ...), so nothing changes for existing pages
• the file is page-owned HTML, so it is served under the same sandbox contract the readme and the custom viewers already use, including the applet_connect widening

That gives us the pinout as a section today, an applet home tomorrow, and no further enum edits for the next idea.

Smaller alternative, if the general form is too much

Add pinout to OVERVIEW_SECTIONS plus a component.viewers.pinout slot, matching the three that exist. It solves the immediate case and leaves the applet problem open.

Why this matters beyond tidiness

We generate pinouts already (adom/component-widgets, and adom-lbr can emit one per part). What we cannot do is put one on a page as anything other than prose, so the flagship's pin map is hand-written HTML that no tool maintains. Blocks with a declared source are how the symbol and footprint stopped being screenshots, and the pinout deserves the same.