Skip to content

docs: fix the dead links to the sample plugin and the stale apiVersion rules - #7

Merged
hamidfzm merged 1 commit into
mainfrom
docs/site-links-and-api-version
Aug 16, 2026
Merged

docs: fix the dead links to the sample plugin and the stale apiVersion rules#7
hamidfzm merged 1 commit into
mainfrom
docs/site-links-and-api-version

Conversation

@hamidfzm

Copy link
Copy Markdown
Member

Summary

The published docs site read as if it did not exist: several links from the README and the docs 404'd, and the site link itself was buried near the bottom of the README. Separately, the apiVersion rules in four places still described the exact-match policy that the compatibility window replaced.

This PR is docs and schema descriptions only. The site's own layout is fixed in #5, which this stacks cleanly on top of (no overlapping files).

Dead links

  • com.glyph.hello-status/ 404'd from the README on GitHub too: the sample plugin lives under plugins/. Now plugins/com.glyph.hello-status/README.md.
  • The docs-site link sat under "Plugin API" at the bottom. It now sits in the second line, with per-page links (Getting Started, Recipes, API Reference, Publishing, Catalog) next to it.

Verified afterwards that every relative link in README.md, CONTRIBUTING.md, docs/*.md, and plugins/*/README.md resolves to a real path.

apiVersion

The host loads anything from PLUGIN_API_COMPAT_FLOOR (0.16.0) up to the running app version. PLUGIN_API_VERSION is __APP_VERSION__, so it moves on every release and is never hand-edited; the floor is the one hand-maintained number. Four places still said "exact match required until 1.0 (currently 0.17.0)":

  • CONTRIBUTING.md entry rules
  • docs/getting-started.md manifest table
  • index.schema.json and plugin.schema.json field descriptions

docs/ecosystem.md also claimed PLUGIN_API_VERSION is "pinned at 0.17.0, bumped by hand", which named the wrong constant. Its "Version flow" list now covers both numbers.

README accuracy

  • The field table predated sha256, category, sandbox, permissions, keywords, and official, and the JSON sample showed "apiVersion": "^1.0.0", which the 0.x policy rejects and which the schema pattern would accept only to have the host refuse it.
  • "Publishing a plugin" told authors to open a PR editing index.json. CONTRIBUTING.md and the validate workflow both forbid that: registrations go in plugins/<id>/plugin.json and the index is generated on merge.

Testing

  • node scripts/build-index.mjs produces no drift, so no generated file is touched.
  • Both schemas still parse and validate the committed registrations.

Not included

docs/api-reference.md is still titled "(0.17.0)" and the template's types/glyph.d.ts header still says 0.17.0, while the host API is at 0.20.0. Bumping those markers means asserting the 0.18 to 0.20 surface is documented, which needs a real audit rather than a find and replace.

…n rules

The README pointed at com.glyph.hello-status/, a path that does not exist:
the sample plugin lives under plugins/. The docs-site link was also buried
under "Plugin API" near the bottom; it now sits in the second line with the
per-page links next to it.

Four places still described apiVersion as an exact match against a hardcoded
"current" version, which the compatibility window replaced. The host accepts
anything from PLUGIN_API_COMPAT_FLOOR (0.16.0) up to the running app version,
and PLUGIN_API_VERSION is the app version rather than a hand-pinned 0.17.0,
so the ecosystem "version flow" section was wrong about which of the two
numbers is maintained by hand.

Also refreshed the README field table, which predated sha256, category,
sandbox, permissions, keywords, and official, and still showed a caret
apiVersion that the 0.x policy rejects. The publishing section told authors
to edit index.json, which CONTRIBUTING and CI both forbid: registrations go
in plugins/<id>/plugin.json and the index is generated on merge.
@hamidfzm hamidfzm self-assigned this Aug 16, 2026
@hamidfzm
hamidfzm merged commit da2dd6c into main Aug 16, 2026
1 check passed
@hamidfzm
hamidfzm deleted the docs/site-links-and-api-version branch August 16, 2026 12:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant