The Glyph Plugin Ecosystem

Three repositories make up the plugin ecosystem. This page maps what lives where and how versions flow between them.

The repos

Repo	What it is	You go there to
hamidfzm/glyph	The app and the plugin host: loader, registries, permission gating, sandbox, marketplace client	Change how plugins run, propose new API surface, report host bugs
glyph-md/plugins (this repo)	The marketplace index (index.json), these docs, and the plugin catalog	Publish or update a plugin, read/write documentation
glyph-md/plugin-template	The scaffold: build setup, types/glyph.d.ts, a working sample	Start a new plugin (click Use this template)

How the pieces connect

plugin author                          user
     │                                   │
     │ scaffolds from                    │ installs via
     ▼                                   ▼
plugin-template ──types track──▶ glyph (host, PLUGIN_API_VERSION)
     │                                   ▲
     │ publishes entry to                │ fetches index.json + main.js,
     ▼                                   │ verifies sha256, checks updates
glyph-md/plugins (plugins/<id>/) ────────┘

• Registrations live one-per-folder under plugins/<id>/; CI generates index.json from them on merge. The app fetches that index.json from this repo's main branch to list marketplace plugins, detect updates (version diff), and install: the packageUrl zip is downloaded, verified against sha256, and only its manifest-declared files are copied out.
• Plugin code itself is not hosted here (except official plugins like Hello Status); each entry's packageUrl points at a release asset in the plugin's own repo, pinned to a tag.
• The template ships type declarations that mirror the host's ctx, so plugin authors get autocomplete without a runtime dependency.
• These docs, the catalog, and every plugin README are published as a website at glyph-md.github.io/plugins, rendered by Glyph's own website export on every merge (dogfooding the export-website action).
• Alongside the aggregate index.json, the generator emits index/<category>.json shards and index/meta.json (per-category counts), so clients can fetch one section instead of everything once the catalog grows.
• Official plugin packages are built and released by CI: bump the version in an official plugin's manifest.json + plugin.json and the release workflow zips the declared files, publishes the tagged release, rewrites packageUrl/sha256, and regenerates the index in one bot commit.

Core and community plugins

Glyph ships some of its own features as core plugins: bundled in the app, listed under Settings, Plugins, Core plugins, and switched on or off there. A disabled core plugin never loads its code. Core plugins register only through the same public plugin API documented here, so every capability they use is available to community plugins too; when one needs something the API lacks, the API grows first. D2 diagrams, Mermaid diagrams, math (KaTeX), the tags pane, backlinks, daily notes, and the Sepia, Solarized, and High contrast theme presets are core plugins today. More app themes can come from community plugins through ctx.ui.addStyles.

The dividing line: a feature is core when it is first-party, works offline, and is useful to most users. It belongs in this marketplace as a community plugin when it is a per-user variant (a spell-check language, a website theme) or depends on a third-party network service. Core plugin ids use the glyph.core. prefix, which the app refuses for installed plugins.

Version flow

Four version numbers matter, and they are linked:

1. PLUGIN_API_VERSION in the app (src/lib/plugins/apiVersion.ts), which is the app version from package.json. It moves on every release, so it is never edited by hand.
2. PLUGIN_API_COMPAT_FLOOR next to it, currently 0.16.0: the oldest declared apiVersion the host still runs unchanged. This is the one hand-maintained number, bumped only in a release that breaks the plugin contract.
3. apiVersion in each plugin's manifest, checked at load time. While the API major is 0 it must fall inside the window between those two; caret ranges only mean something from 1.0.0.
4. version of each plugin: its own semver, used by the marketplace to offer updates.

The maintenance convention: every app PR that changes the plugin API updates, in the same delivery,

• api-reference.md here, with an "(API X.Y)" marker on the new section,
• the template's types/glyph.d.ts (header comment states the version),
• index.schema.json if the manifest grew a field,
• recipes.md if a new contribution point landed.

So the doc markers, the template types, and the host constant always describe the same API.