docs(plugins): plugin CLI, manifest & authoring-shape docs (#1040, #1057)#1059
Open
ascorbic wants to merge 1 commit into
Open
docs(plugins): plugin CLI, manifest & authoring-shape docs (#1040, #1057)#1059ascorbic wants to merge 1 commit into
ascorbic wants to merge 1 commit into
Conversation
… changes (#1040, #1057) Adds migration guides for site operators and plugin authors, new reference pages for emdash-plugin.jsonc and the emdash-plugin CLI, and rewrites the sandboxed-plugin guides to the new default-export shape. Migration guides follow Astro's breaking-changes format; Atmosphere account terminology used throughout.
|
Contributor
Scope checkThis PR changes 1,278 lines across 14 files. Large PRs are harder to review and more likely to be closed without review. If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs. See CONTRIBUTING.md for contribution guidelines. |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-perf-coordinator | 09c6ce9 | May 16 2026, 10:44 AM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-i18n | 09c6ce9 | May 16 2026, 10:44 AM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | 09c6ce9 | May 16 2026, 10:45 AM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-playground | 09c6ce9 | May 16 2026, 10:45 AM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-demo-cache | 09c6ce9 | May 16 2026, 10:46 AM |
@emdash-cms/admin
@emdash-cms/auth
@emdash-cms/blocks
@emdash-cms/cloudflare
emdash
create-emdash
@emdash-cms/gutenberg-to-portable-text
@emdash-cms/x402
@emdash-cms/plugin-ai-moderation
@emdash-cms/plugin-atproto
@emdash-cms/plugin-audit-log
@emdash-cms/plugin-color
@emdash-cms/plugin-embeds
@emdash-cms/plugin-forms
@emdash-cms/plugin-webhook-notifier
commit: |
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the new sandboxed plugin authoring shape and toolchain introduced by the plugin CLI/manifest work (referencing #1040 and the in-flight #1057), and rewrites the plugin docs set to match the new model for site operators and plugin authors.
Changes:
- Adds new migration guides for site operators and plugin authors covering the CLI rename and the new default-export + manifest-based authoring shape.
- Adds new reference pages for
emdash-plugin.jsoncand theemdash-pluginCLI, and updates existing “creating plugins” docs to use them. - Wires the new docs pages into the Starlight sidebar.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/plugins/upgrading-sites.mdx | New site-operator migration guide for CLI rename + default export plugins. |
| docs/src/content/docs/plugins/creating-plugins/your-first-plugin.mdx | Rewrites tutorial to the new manifest + src/plugin.ts authoring shape and new CLI flow. |
| docs/src/content/docs/plugins/creating-plugins/storage.mdx | Updates storage docs to declare storage in the manifest and use the new runtime export shape. |
| docs/src/content/docs/plugins/creating-plugins/settings.mdx | Updates settings docs to new sandboxed authoring/runtime shape + manifest-declared admin pages. |
| docs/src/content/docs/plugins/creating-plugins/publishing.mdx | Rewrites publishing docs for Atmosphere identity model + hosted tarball publishing. |
| docs/src/content/docs/plugins/creating-plugins/migrating-to-the-cli.mdx | New plugin-author migration guide from definePlugin() to satisfies SandboxedPlugin + manifest/CLI build. |
| docs/src/content/docs/plugins/creating-plugins/manifest.mdx | New manifest reference page (identity/profile/trust contract/publisher pinning). |
| docs/src/content/docs/plugins/creating-plugins/hooks.mdx | Updates hook signature guidance to rely on satisfies SandboxedPlugin inference. |
| docs/src/content/docs/plugins/creating-plugins/cli.mdx | New CLI reference page for emdash-plugin commands and outputs. |
| docs/src/content/docs/plugins/creating-plugins/choosing-a-format.mdx | Updates sandboxed-vs-native comparison to the new authoring shape terminology. |
| docs/src/content/docs/plugins/creating-plugins/capabilities.mdx | Moves capability declarations to the manifest and updates validation guidance. |
| docs/src/content/docs/plugins/creating-plugins/block-kit.mdx | Updates Block Kit examples to the new sandboxed plugin export shape. |
| docs/src/content/docs/plugins/creating-plugins/api-routes.mdx | Updates route examples/signature notes for the new sandboxed plugin typing model. |
| docs/astro.config.mjs | Adds new docs pages to the plugins sidebar navigation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| </Steps> | ||
|
|
||
| `--validate-only` skips tarball creation but still produces the `dist/` artifacts — "validate" implies "build first". |
Comment on lines
+66
to
+75
| ## Profile | ||
|
|
||
| These feed the registry listing. `license` and a security contact are required; the rest are optional. | ||
|
|
||
| | Field | Required | Notes | | ||
| | -------------------------- | -------- | ------------------------------------------------------------------ | | ||
| | `license` | Yes | SPDX expression (`"MIT"`, `"Apache-2.0"`, `"MIT OR Apache-2.0"`). Used on first publish; the existing profile wins on later publishes. | | ||
| | `author` / `authors` | Yes | One of the two. `author: { name, url?, email? }` for a single author; `authors: [...]` (≤ 32) for several. Setting both is an error. | | ||
| | `security` / `securityContacts` | Yes | One of the two. Each contact needs at least one of `email` or `url`. `securityContacts: [...]` (≤ 8) for several. Setting both is an error. | | ||
| | `name` | No | Display name. Defaults to the slug. | |
| ## Prerequisites | ||
|
|
||
| ## Bundle format | ||
| - A valid [`emdash-plugin.jsonc`](/plugins/creating-plugins/manifest/) with `slug`, `publisher`, `license`, and a security contact. Run `emdash-plugin validate` to confirm. |
|
|
||
| Replace the `definePlugin()` wrapper with a bare object and a `satisfies` annotation: | ||
|
|
||
| ```ts del={1} ins={2} "} satisfies SandboxedPlugin;" |
Comment on lines
58
to
+68
| "scripts": { | ||
| "build": "tsdown src/index.ts src/sandbox-entry.ts --format esm --dts --clean" | ||
| "build": "emdash-plugin build", | ||
| "dev": "emdash-plugin dev" | ||
| }, | ||
| "peerDependencies": { | ||
| "emdash": "*" | ||
| "emdash": ">=0.12.0" | ||
| }, | ||
| "devDependencies": { | ||
| "emdash": "*", | ||
| "tsdown": "^0.6.0", | ||
| "typescript": "^5.5.0" | ||
| "@emdash-cms/plugin-cli": ">=0.1.0", | ||
| "emdash": ">=0.12.0", | ||
| "typescript": "^5.9.0" |
| "emdash": "*", | ||
| "tsdown": "^0.6.0", | ||
| "typescript": "^5.5.0" | ||
| "@emdash-cms/plugin-cli": ">=0.1.0", |
11 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Documents the plugin CLI / manifest / authoring-shape changes from #1040 (merged) and #1057 (open).
plugins/upgrading-sites) —@emdash-cms/registry-cli→@emdash-cms/plugin-clirename, and the named-export → default-export change forplugin-audit-log,plugin-webhook-notifier,plugin-atproto.plugins/creating-plugins/migrating-to-the-cli) —definePlugin()→satisfies SandboxedPlugin, two-file →src/plugin.ts+emdash-plugin.jsonc,tsdown→emdash-plugin build/dev, type renames for sandbox-runner authors.emdash-plugin.jsoncmanifest (fields, trust contract, publisher pinning) and theemdash-pluginCLI (init/build/dev/validate/bundle/publish), plus a "Your Atmosphere account" section.your-first-plugin,publishing(now the Atmosphere/atproto model),storage,api-routes,settings,capabilities,block-kit,hooks,choosing-a-format. Native-plugin docs left untouched (unaffected by feat(plugin-cli): sandboxed plugin authoring + build + dev (with rename) #1057).docs/astro.config.mjs.Both migration guides follow Astro's breaking-changes format (per-change entries with a "What should I do?" section and minimal Expressive Code diffs). Atmosphere account terminology is used throughout, cross-linked to the existing Atmosphere login guide and atmosphereaccount.com.
Note
This documents the open PR #1057. It should merge with or after #1057, since it describes that PR's behavior. #1040 is already merged.
Closes #
Type of change
Checklist
pnpm typecheckpasses — N/A, docs-only (content)pnpm lintpasses — N/A, docs-only (content)pnpm testpasses (or targeted tests for my change) — N/A, docs-onlypnpm formathas been run — N/A, oxfmt does not format.mdx; frontmatter/JSX/fence/link/anchor checks done manuallyAI-generated code disclosure
Screenshots / test output
Full
astro buildis blocked locally by a pre-existing Cloudflare env issue (AI_SEARCHbinding instance missing) unrelated to content. Validated instead: frontmatter, JSX tag balance, code-fence parity, internal links, and heading anchors across all touched pages.