docs: revamp develop-plugin section by crazywoola · Pull Request #784 · langgenius/dify-docs

crazywoola · 2026-05-19T07:50:23Z

Summary

End-to-end refresh of the develop-plugin documentation section: fixes critical content bugs surfaced by a full audit, restructures the Publishing sidebar around the developer's mental model, and adds onboarding scaffolding for newcomers.

Critical content bugs fixed

CLI Linux instructions showed the Mac binary name (dify-plugin-darwin-arm64). Also added a Windows tab.
release-to-individual-github-repo.mdx was a verbatim duplicate of release-overview.mdx with zero GitHub-publishing instructions. Replaced with the actual flow: create repo → push code → dify plugin package → upload .difypkg to a release → install via Dify's "From GitHub".
REMOTE_INSTALL_HOST/REMOTE_INSTALL_PORT in cli.mdx, develop-md-exporter.mdx, and creating-new-model-provider.mdx: the plugin SDK only honors REMOTE_INSTALL_URL (combined host:port). The wrong env vars silently fail.
plugin-auto-publish-pr.mdx used runs-on: depot-ubuntu-24.04 (a Depot.dev paid runner most users don't have). Switched to ubuntu-latest and added workflow_dispatch: to match every published example in dify-official-plugins.
Flomo walkthrough YAML used non-existent credential_schema: / tool_schema: keys. Rewrote to the canonical provider + tool yaml structure (credentials_for_provider, separate tools/*.yaml).
Reverse-invocation examples had leaked review comments ("Assuming NodeResponse is importable", "Assuming ClassConfig is defined", "Note: the original example incorrectly called…"). Verified the imports against dify-plugin-sdks (NodeResponse, ClassConfig both exported from dify_plugin.entities.workflow_node) and removed the leakage.
reverse-invocation-model.mdx had a wrong type signature: def invoke(self, model_config: TextEmbeddingResult, ...) should be TextEmbeddingModelConfig. Confirmed against src/dify_plugin/invocations/model/text_embedding.py.
agent-strategy-plugin.mdx said the packaged file would be google.difypkg; the example plugin is basic_agent.
tool-oauth.mdx pinned dify_plugin>=0.4.2,<0.5.0, conflicting with datasource-plugin.mdx's >=0.5.0. Aligned to >=0.5.0, matching the bulk of dify-official-plugins.
customizable-model.mdx contained some NOT IMPORTANT code here as a code-block placeholder.
code-of-conduct.mdx had a stray bold token (**free** plugins.).
Missing frontmatter description on 7 pre-existing pages (CLAUDE.md violation).

Structural changes

docs.json Publishing tree (English block only — zh/ja sync automatically):

Publishing
├── release-overview                       ← promoted to section landing
├── Standards
├── Marketplace
│   ├── release-to-dify-marketplace
│   └── plugin-auto-publish-pr             ← nested as Marketplace helper
├── GitHub Repository
├── Local File
└── FAQ

Getting Started gets a new choose-plugin-type.mdx (decision matrix) between the intro and the CLI page.

Major rewrites and expansions

remote-debug-a-plugin.mdx: 50 → 160 lines with prerequisites, cloud vs. self-hosted Tabs, env-var matrix, troubleshooting Accordions.
multilingual-readme.mdx: added README template, structure recommendations, and language-code matching note.
faq.mdx: 2 → 10 entries covering packaging, signature verification, package size, Python pin, OAuth callback URL, marketplace timeline, storage scope.
plugin-auto-publish-pr.mdx: 145-line inline YAML wrapped in an Accordion with a one-sentence summary above.

Polish

"Quick Decision" callouts at the top of model-schema.mdx (per-model-type method matrix) and model-designing-rules.mdx (configurate_methods chooser).
Landing-page CardGroup pointing first-time visitors at choose-plugin-type and CLI.

Code verification

External API claims verified against live source:

Claim	Verified against
CLI release asset names per OS	`dify-plugin-daemon` 0.6.1 release assets
`NodeResponse` import path and fields	`dify-plugin-sdks` `src/dify_plugin/entities/workflow_node.py`
`ClassConfig` import path	Same file
`LLMInvocation.invoke` signature	`dify-plugin-sdks` `src/dify_plugin/invocations/model/llm.py`
`TextEmbeddingInvocation.invoke` signature	`dify-plugin-sdks` `src/dify_plugin/invocations/model/text_embedding.py`
`ToolInvocation.invoke_builtin_tool` / `_workflow_tool` / `_api_tool`	`dify-plugin-sdks` `src/dify_plugin/invocations/tool.py`
Auto-publish workflow YAML shape	`dify-official-plugins` `tools/{deepl,supabase,onedrive}/.github/workflows/plugin-publish.yml`
`credentials_for_provider` shape	`dify-official-plugins` `tools/gitlab/provider/gitlab.yaml`
`REMOTE_INSTALL_URL` env var	`dify-plugin-daemon` `cmd/commandline/plugin/templates/.env.example`

Test plan

mintlify dev and walk every page in the new Publishing tree
Verify the GitHub-from-repo install flow against current Dify cloud
Sanity-check the plugin-auto-publish-pr.mdx workflow YAML against langgenius/dify-plugins main
SME review on reverse-invocation pages (graphon/runtime maintainer)
Translation pipeline regenerates zh/ and ja/

🤖 Generated with Claude Code

Fixes critical content bugs that broke setup paths (wrong Linux binary name, conflicting `REMOTE_INSTALL_URL` env var, full duplicate of release-overview where GitHub-publishing steps should be, broken Flomo provider YAML, depot-only `runs-on` in the auto-publish workflow, unverified imports in reverse-invocation examples, wrong `TextEmbeddingModelConfig` type) and restructures the section around the developer's mental model. Sidebar reorg: Publishing now reads release-overview -> Standards -> Marketplace (with auto-publish nested) -> GitHub Repository -> Local File -> FAQ. A new choose-plugin-type decision page sits between the landing page and the CLI in Getting Started. Major rewrites: release-to-individual-github-repo (full), remote-debug-a-plugin (50 -> 160 lines with troubleshooting), multilingual-readme (added template), faq (2 -> 10 entries), Flomo walkthrough YAML to canonical credentials_for_provider shape. Quick Decision callouts on model-schema and model-designing-rules. Backfilled missing frontmatter `description` on 7 pre-existing pages for CLAUDE.md compliance. All edits in en/ only; translation pipeline handles zh/ja. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

mintlify · 2026-05-19T07:50:28Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dify-core-product	🟢 Ready	View Preview	May 19, 2026, 7:53 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Copilot

Pull request overview

Refreshes the develop-plugin documentation to fix audited inaccuracies, add missing page metadata, and reorganize Getting Started + Publishing content to match common developer workflows.

Changes:

Reworked Publishing navigation (overview landing + separate Marketplace/GitHub/Local File groupings) and added/expanded supporting docs (FAQ, GitHub releases flow).
Fixed multiple correctness issues in examples/instructions (CLI install guidance, REMOTE_INSTALL_URL, reverse-invocation signatures/usages, packaging name).
Added onboarding scaffolding and page descriptions (new “Choose a Plugin Type” page, Getting Started landing cards, expanded remote debugging guidance).

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct.mdx	Fixes formatting in monetization policy bullet.
en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo.mdx	Replaces duplicated content with an end-to-end GitHub-release distribution flow.
en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr.mdx	Updates workflow guidance (runner + manual trigger) and wraps full YAML in an Accordion.
en/develop-plugin/publishing/faq/faq.mdx	Expands FAQ with packaging/install/debugging/OAuth/Marketplace answers and updated env var guidance.
en/develop-plugin/getting-started/getting-started-dify-plugin.mdx	Adds description + “Start here” cards to improve onboarding entry points.
en/develop-plugin/getting-started/cli.mdx	Corrects Linux CLI instructions, adds Windows guidance, and fixes remote debug env var usage.
en/develop-plugin/getting-started/choose-plugin-type.mdx	New decision matrix page to route users to the right plugin type.
en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin.mdx	Major rewrite with prerequisites, cloud/self-hosted notes, and troubleshooting.
en/develop-plugin/features-and-specs/plugin-types/plugin-logging.mdx	Adds missing frontmatter description.
en/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest.mdx	Adds missing frontmatter description.
en/develop-plugin/features-and-specs/plugin-types/multilingual-readme.mdx	Clarifies multilingual README file layout and adds recommended README structure guidance.
en/develop-plugin/features-and-specs/plugin-types/model-schema.mdx	Fixes incorrect cross-link and adds quick “which method to implement” matrix.
en/develop-plugin/features-and-specs/plugin-types/model-designing-rules.mdx	Clarifies Provider vs AIModelEntity relationship and adds configurate_methods decision cards.
en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-node.mdx	Cleans leaked review notes and corrects imports/usage notes for workflow node invocation.
en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-model.mdx	Fixes tool parameter name and corrects TextEmbedding invoke signature.
en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app.mdx	Removes leaked review notes and cleans up formatting in endpoint example.
en/develop-plugin/features-and-specs/advanced-development/customizable-model.mdx	Replaces placeholder code block text with a clearer omission note.
en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin.mdx	Adds missing frontmatter description.
en/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx	Adds description and aligns SDK version guidance to `dify_plugin>=0.5.0`.
en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx	Adds missing frontmatter description.
en/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx	Fixes remote debug env vars to use `REMOTE_INSTALL_URL`.
en/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx	Fixes Linux CLI instructions, corrects tool/provider YAML structure, and updates remote debug env vars.
en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx	Adds missing frontmatter description.
en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx	Fixes remote debug env vars to use `REMOTE_INSTALL_URL`.
en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx	Adds description and corrects example packaged filename.
docs.json	Reorganizes Develop Plugin sidebar (adds new Getting Started page, reshapes Publishing tree).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

TOC: promote leading h3 -> h2 (and h4 -> h3) on 17 pages whose right-rail TOC had no top-level entries because every section started at h3. Hierarchy is preserved; subsections that were h4 now sit correctly as h3 under their parent h2. Standards section: rewrite contributor-covenant-code-of-conduct (now properly titled "Plugin Development Guidelines") and privacy-protection-guidelines for tighter prose, scannable lists, and correct heading levels. The privacy page used h4 manual numbering which broke its TOC entirely; now uses h2/h3 with an Accordion FAQ. Reclassify third-party-signature-verification: it is a Community Edition install-time feature, not a Marketplace standard. Moved from Publishing > Standards to Publishing > Local File (alongside the release-by-file `.difypkg` flow). Also strip a stray `# Endpoint` h1 from endpoint.mdx (the title is already in frontmatter) and replace a self-referencing link. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Walkthroughs sidebar: split the 12-page flat list into Cheatsheet + 'By Plugin Type' subgroup (tool/oauth/model/agent-strategy/datasource/ trigger/endpoint) + 'Full Walkthroughs' subgroup (flomo/slack-bot/ md-exporter/multimodal). Shortened the worst sidebar offenders: - 'Build Tool Plugins for Multimodal Data Processing in Knowledge Pipelines' -> 'Multimodal Tool' - '10-Minute Guide to Building Dify Plugins' -> 'Flomo Tool (10-min)' - 'Dify Plugin Development Cheatsheet' -> 'Cheatsheet' - 'Develop A Slack Bot Plugin' -> 'Slack Bot' - 'Build a Markdown Exporter Plugin' -> 'Markdown Exporter' - 'Add OAuth Support to Your Tool Plugin' -> 'Tool OAuth' - 'Neko Cat Endpoint' -> 'Endpoint Plugin' Publishing pages: rewrite around Mintlify widgets and bake in the actual reviewer process from the pr-review-helper skill: - release-to-dify-marketplace.mdx: full rewrite with a Tabs-based pre-submission checklist, the exact 12-check reviewer table the automated workflow runs, a Steps submit flow, AccordionGroup FAQ, CardGroup related resources, and a PR-lifecycle table. - release-overview.mdx: replace prose with a CardGroup chooser and a comparison table (audience / review / install path / versioning / best for). - release-by-file.mdx: Steps for both packaging and installing, CardGroup for next-step distribution methods. - third-party-signature-verification.mdx: scenario CardGroup, three-Step generate/sign/verify flow, three-Step daemon-enable flow. - faq.mdx: add 'Why was my Marketplace PR rejected?' entry covering the most common automated-check failures from the skill. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

github-actions · 2026-05-19T08:25:19Z

🌐 Multi-language Sync

✅ Created sync PR #785

Synced 19 files to cn + jp

⚠️ 1 file failed:

zh/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx

Both PRs can merge independently. Future commits here will auto-update the sync PR.

Copilot

Pull request overview

Copilot reviewed 39 out of 39 changed files in this pull request and generated 3 comments.

- release-to-dify-marketplace.mdx: replace the static PNG submission flowchart with a Mermaid diagram (renders dark-mode-friendly, diff-friendly, no CDN dependency). Add Check callout confirming auto-publish on merge. - tool-oauth.mdx: add a Mermaid sequence diagram contrasting the admin-side OAuth client setup with the per-user authorization flow, matching the existing "two separate flows" narrative. - release-overview.mdx: add inline `<Icon>` to the comparison table header so each column reads as Marketplace/GitHub/Local at a glance. - remote-debug-a-plugin.mdx, release-by-file.mdx, release-to-individual-github-repo.mdx: add `<Check>` confirmations after the verify-install step on each install path, so the reader knows what "success" looks like and when they can stop following. Snippets deferred — the translation pipeline operates on en/zh/ja trees, so a root-level `snippets/` directory needs coordination with tools/translate before adoption. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Auto-generated translations for changes in commit 626b116. Last-Processed-Commit: 626b116 Original-PR: #784 Languages: Chinese (zh), Japanese (ja) 🤖 Generated with GitHub Actions

github-actions · 2026-05-19T08:54:54Z

🌐 Multi-language Sync

✅ Updated sync PR #785

Synced 20 files to cn + jp

Future commits will auto-update the sync PR.

Copilot

Pull request overview

Copilot reviewed 39 out of 39 changed files in this pull request and generated 3 comments.

github-actions · 2026-05-19T11:22:04Z

🌐 Multi-language Sync

✅ Updated sync PR #785

Synced 20 files to cn + jp

Future commits will auto-update the sync PR.

Auto-generated translations for changes in commit 30b5781. Last-Processed-Commit: 30b5781 Original-PR: #784 Languages: Chinese (zh), Japanese (ja) 🤖 Generated with GitHub Actions

Auto-generated translations for changes in commit 7bdfeb6. Last-Processed-Commit: 7bdfeb6 Original-PR: #784 Languages: Chinese (zh), Japanese (ja) 🤖 Generated with GitHub Actions

github-actions · 2026-05-19T12:20:35Z

🌐 Multi-language Sync

✅ Updated sync PR #785

Synced 4 files to cn + jp

⚠️ 2 files failed

Future commits will auto-update the sync PR.

* 🌐 Initial translations for PR #784 Auto-generated translations for documentation changes in PR #784. Last-Processed-Commit: 0c74e87 Original-PR: #784 Languages: Chinese (zh), Japanese (ja) 🤖 Generated with GitHub Actions * 🔄 Update translations for commit 626b116 Auto-generated translations for changes in commit 626b116. Last-Processed-Commit: 626b116 Original-PR: #784 Languages: Chinese (zh), Japanese (ja) 🤖 Generated with GitHub Actions * 🔄 Update translations for commit 30b5781 Auto-generated translations for changes in commit 30b5781. Last-Processed-Commit: 30b5781 Original-PR: #784 Languages: Chinese (zh), Japanese (ja) 🤖 Generated with GitHub Actions * 🔄 Update translations for commit 7bdfeb6 Auto-generated translations for changes in commit 7bdfeb6. Last-Processed-Commit: 7bdfeb6 Original-PR: #784 Languages: Chinese (zh), Japanese (ja) 🤖 Generated with GitHub Actions --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

crazywoola requested a review from RiskeyL as a code owner May 19, 2026 07:50

Copilot AI review requested due to automatic review settings May 19, 2026 07:50

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. documentation Improvements or additions to documentation labels May 19, 2026

Copilot started reviewing on behalf of crazywoola May 19, 2026 07:51 View session

mintlify Bot deployed to staging May 19, 2026 07:52 View deployment

Copilot AI reviewed May 19, 2026

View reviewed changes

Comment thread en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr.mdx Outdated

Comment thread en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin.mdx

mintlify Bot deployed to staging May 19, 2026 08:09 View deployment

Copilot AI review requested due to automatic review settings May 19, 2026 08:21

Copilot started reviewing on behalf of crazywoola May 19, 2026 08:22 View session

mintlify Bot deployed to staging May 19, 2026 08:22 View deployment

github-actions Bot mentioned this pull request May 19, 2026

🌐 Sync PR #784 translations: docs: revamp develop-plugin section #785

Merged

Copilot AI reviewed May 19, 2026

View reviewed changes

mintlify Bot deployed to staging May 19, 2026 08:32 View deployment

RiskeyL added 3 commits May 19, 2026 17:46

fix: address correctness gaps in develop-plugin pages

7f1fe25

docs: align plugin type catalog and tighten heading case

5860a61

style: drop em dashes and tidy formatting in develop-plugin docs

30b5781

Copilot AI review requested due to automatic review settings May 19, 2026 10:42

Copilot started reviewing on behalf of RiskeyL May 19, 2026 10:43 View session

mintlify Bot deployed to staging May 19, 2026 10:44 View deployment

Copilot AI reviewed May 19, 2026

View reviewed changes

Comment thread en/develop-plugin/publishing/standards/third-party-signature-verification.mdx Outdated

Comment thread en/develop-plugin/publishing/faq/faq.mdx Outdated

Comment thread en/develop-plugin/features-and-specs/plugin-types/plugin-logging.mdx Outdated

fix: address Copilot follow-up comments on develop-plugin docs

7bdfeb6

mintlify Bot deployed to staging May 19, 2026 12:16 View deployment

RiskeyL merged commit f06cf8d into main May 21, 2026
3 checks passed

RiskeyL deleted the docs/revamp-develop-plugin-section branch May 21, 2026 13:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: revamp develop-plugin section#784

docs: revamp develop-plugin section#784
RiskeyL merged 8 commits into
mainfrom
docs/revamp-develop-plugin-section

crazywoola commented May 19, 2026

Uh oh!

mintlify Bot commented May 19, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

crazywoola commented May 19, 2026

Summary

Critical content bugs fixed

Structural changes

Major rewrites and expansions

Polish

Code verification

Test plan

Uh oh!

mintlify Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

🌐 Multi-language Sync

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

🌐 Multi-language Sync

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

🌐 Multi-language Sync

Uh oh!

github-actions Bot commented May 19, 2026

🌐 Multi-language Sync

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mintlify Bot commented May 19, 2026 •

edited

Loading