a2nr
/
velxio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
velxio/frontend/src/components/component-docs
History
David Montero Crespo 2c000e3aaf docs(ssd1306): a datasheet per variant, each with its own pinout 
Both SSD1306 modules are real parts and both belong in the catalogue -
the mismatch was in the docs, not the parts:
 - the 8-pin Adafruit breakout was served a datasheet listing a 4-pin
   I2C pinout (VCC/GND/SCL/SDA) that is not its header at all; it now
   documents its own 9-way pinout with the I2C and SPI role of each pin;
 - the 4-pin I2C module had NO datasheet, because docs resolve by
   component id and ssd1306-i2c-4pin.md did not exist - so the part
   showed nothing. It has one now.
Each points at the other so it is obvious which one you want.
 		2026-08-20 15:03:09 +02:00
..
displays docs(ssd1306): a datasheet per variant, each with its own pinout 2026-08-20 15:03:09 +02:00
input
…
output
…
sensors
…
README.md
…

README.md

Component datasheets

Hand-authored Markdown shown in the Component Picker's hover panel (ComponentInfoPanel). One file per component:

component-docs/<category>/<id>.md

Full authoring guide (with a per-component id checklist): docs/wiki/component-datasheets.md

  • <id> MUST match the component id in public/components-metadata.json (the loader in componentDocs.ts matches by filename and ignores the category folder, so the folder is purely for tidiness).
  • <category> — pick the closest ComponentCategory (sensors, displays, input, output, motors, passive, logic, analog, electromech, boards, other).
  • Keep it scannable. The panel is a hover popover — a good doc is a one-line overview, a pinout table, a few spec bullets, and one wiring tip. The panel is scrollable, so longer datasheets are fine; front-load the essentials.
  • GitHub-flavoured Markdown is supported (tables, lists, `code`, bold, links). Raw HTML is not rendered (react-markdown default).

Front-matter (optional)

A doc may start with a small ----delimited block giving the component's brand and a purchase link. Both are optional; when present the panel shows a "by " line under the title and a Buy button in the footer.

---
brand: Aosong (AM2302)
buy: https://www.example.com/product/dht22
---
Body markdown starts here…
  • brand — manufacturer / brand name (plain text).
  • buy — purchase URL. Must be http(s):// (other schemes are ignored for safety). The seeded docs use vendor search URLs as placeholders — swap them for the real product or affiliate link.

The panel already lists the live default Properties from metadata below your doc, so don't repeat property defaults here — focus on what the JSON can't express: how the part works, its pinout, wiring, and gotchas.

Adding a doc

  1. Create component-docs/<category>/<id>.md.
  2. Write the overview + pinout + tips.
  3. That's it — the file is picked up automatically (Vite import.meta.glob), loaded on first hover and cached. No registration needed.