[Propsal] Dynamical Frontend Render Plugin

[lunny]

Preface

#34794 introduced a frontend static render plugin machism. I believe we can add more plugins in the future. But that will bloat the binary size and we cannot accept all the possible plugins. So that we need a machism to allow users(instance administrator) to find/install/uninstall Gitea Render Plugins.

Design Goals

There are 5 kinds of renders in Gitea.

• Render a file in the git/git lfs
• Render a file in the wiki
• Render part of content in a markdown file/issue content/comment content
• Render part of content in a diff compare page (i.e. an image changed between 2 commits)
• Preview in the web editor

This plugin system should support rendering a file in the git/git lfs at least.

The Gitea Frontend Render Plugin system aims to introduce a flexible, modular architecture that allows instance administrators to extend Gitea’s file rendering capabilities without modifying the core binary. Inspired by modern plugin-based ecosystems (e.g., VSCode extensions, browser plugins), this mechanism empowers the community to develop, share, and deploy custom renderers for specific file types (e.g., Markdown with diagrams, PDF, AsciiDoc, Jupyter notebooks, etc.).

A render plugin is a JavaScript (or TypeScript-transpiled) module that conforms to a defined Gitea rendering interface and is dynamically loaded by the frontend at runtime. It is designed to safely extend the rendering capabilities of Gitea views, in a secure and sandboxed way.

• Pluggability: Support multiple independently developed renderers.
• Discoverability: Administrators should be able to easily discover and install plugins.
• Configurability: Allow instance-level control over which plugins are enabled or disabled.
• Lightweight core: Keep the core Gitea binary minimal by externalizing optional renderers.

Relationship with current renderers

Gitea currently have supported backend renderers for markdown/csv and som other files. And recently Gitea introduced a frontend static plugin system which could render pdf and 3D images. The current plugin system could be kept there and the dynamic plugins mentioned in this proposal could be loaded as a special frontend static plugin. That means creating a plugin in web_src/js/render/plugins/dynamic-plugin.ts. The dynamic plugins will be loaded according to the conditions in that file.

Plugin Format

Each plugin could be a .zip archive or an online git url which containing the following structure:

my-plugin.zip / repository folder
├── manifest.json     # Plugin metadata
├── render.js             # Entrypoint script
├── assets/                # Optional static assets (CSS, icons, fonts, etc.)

manifest.json example:

{
  "id": "pdf-renderer", // unique for every Gitea instance
  "name": "PDF Renderer",
  "version": "1.0.0",
  "description": "Render PDF files directly in the Gitea file view.",
  "entry": "render.js",
  "filePatterns": ["*.pdf"]
}

Plugin Storage and Delivery

To ensure security, performance, and compatibility with Gitea’s deployment model, all frontend render plugins must be downloaded and stored under a specific Gitea-managed directory, and served through Gitea’s internal HTTP router. This design avoids external dependency loading (e.g., from CDN or untrusted domains), ensuring all assets are locally verifiable and cacheable.

Storage Path

Uploaded/Downloaded plugin archives (.zip) will be extracted to a designated path inside the Gitea data/ directory. For example:

<gitea-root>/data/render-plugins/
├── pdf-renderer/
│   ├── manifest.json
│   ├── render.js
│   └── assets/
└── 3d-renderer/
    ├── manifest.json
    └── render.js

This allows Gitea to:
• Serve static assets securely via router
• Perform updates or uninstalls by removing plugin directories

Storage of Plugin State

Enabled status is stored in Gitea’s database under a new table (e.g., render_plugin):

type RenderPlugin struct {
   ID int64
   Name string `xorm:"unique"`
   Source string // this could be uploaded or a url
   Version string
   Description string
   Enabled bool
   InstalledAt util.timestamp
   UpdatedAt util.timestamp
}

Serving via Gitea Router

Gitea will expose plugin files through a well-defined route, e.g.

/assets/render-plugins // list all enabled render plugins metadata, this could be generated dynamically when install/uninstall plugins

/assets/render-plugins/pdf-renderer/render.js // main entry of one plugin

/assets/render-plugins/3d-renderer/assets/style.css // possible css file of one plugin

Admin UI Flow

On the Site Administration > Render Plugins page, admins will be able to:
• See a list of all installed plugins
• View plugin details (name, description, version)
• Enable/Disable plugin via toggle switch
• Delete plugin (removes files and DB entry)

Installation Flow

1.	Admin uploads plugin ZIP file or an via Gitea Admin Panel when creating a new plugin or upgrading a plugin
2.	Gitea validates the manifest, extracts it to data/render-plugins/.
3.	Plugin assets become accessible via routes.

Delete Plugin

When delete plugin, it will be removed from disk assets/ directory and database.

Enable/Disable Plugin

When enable/disable plugins, the database will be updated and the plugins meta files will be updated.

[wxiaoguang]

It needs to maintain the compatibility correctly. Propose a feasible plan before writing code.

[lunny]

Maybe the current plugin system could be kept there and the dynamic plugins mentioned in this proposal could be loaded as a special plugin. That means creating a plugin in web_src/js/render/plugins/dynamic-plugin.ts. The dynamic plugins will be loaded according to the conditions in that file.

[silverwind]

I think instead of manifest.json, we could leverage the existing package.json spec. The script itself should export a async function as its ESM default export that is imported and called by our code with likely a File blob to render and a destination DOM element to render to. opts for any additional options passed from gitea. Here's an example:

export default async function render(file: File, target: HTMLElement, opts: Record<string, any>): Promise<void> {
  target.innerHTML = "result";
}

[kerwin612]

Here’s a concrete plan for how this can be implemented in Gitea, step by step:

1. Plugin Packaging

• Each plugin is a zip archive (or git repo) containing either a manifest.json or package.json, plus a JS entry file (render.js) and optional assets.
• The manifest file must include:
  • id / name (unique string)
  • version
  • filePatterns (array, e.g. ["*.pdf"]) OR MIME-TYPE???
  • entry (relative path to main JS file)
  • description (optional)

2. Backend: Storage & Serving

• Uploaded plugin zips are extracted to data/render-plugins/<plugin-id>/.
• All plugin files are served via Gitea’s internal static route, e.g. /assets/render-plugins/pdf-renderer/render.js.
• Add a new DB table render_plugin to track installed plugins, their metadata, and enabled/disabled status.(Maybe we don't need a data table and can directly load the currently uploaded plugins dynamically?)

3. Admin UI

• Add a new admin page listing all plugins (id, name, version, status).
• Support upload (zip or git), enable/disable, and delete.
• On upload, backend validates manifest/package.json, extracts files, and updates DB.

4. Frontend: Plugin Loading & Registration

• On file view, frontend fetches all enabled plugin manifests.
• For each file, match filePatterns and dynamically import the plugin’s render.js using ES module import.
• Each plugin must export at least:
  • canHandle(filename, mimeType): boolean
  • render(container, fileUrl): Promise
• Only call render() if canHandle() returns true.

5. Security

• Only load plugins from local assets, never from external URLs.
• Plugins run in a restricted context. If needed, can add iframe sandboxing later.
• No access to Gitea internals or user data beyond what’s explicitly passed in.

6. Fallback

• If no plugin matches, or plugin fails, fallback to the default file view.
• Existing built-in renderers remain as fallback for now.

[silverwind]

You can just use package.json only, the properties there are not strict, so you can easily add additional custom properties:

{
  "name": "myplugin",
  "version": "1.2.3",
  "gitea": {
    "type": "render-plugin",
    "filePatterns": ["*.foo"],
    "mimePatterns": ["text/foo"],
  },
}

There is not need for a entry because package.json already has that: https://nodejs.org/api/packages.html#package-entry-points. The spec for entry points is quite complicated, maybe initially only support "exports": "./index.js" syntax.

The benefit of being a valid npm package is that it can be published to npm registry for easy distribution. The whole zip file stuff could be skipped and plugins could be specified as npm package name only (downloaded on startup).

[wxiaoguang]

• filePatterns (array, e.g. ["*.pdf"]) OR MIME-TYPE???

I do not think it is complete.

You should be able to answer the question by resolving "render a text-based STL 3D model correctly".

Each plugin must export at least:
* canHandle(filename, mimeType): boolean
* render(container, fileUrl): Promise

What if we need to change/re-design the plugin API in the future? #34917 (comment) It needs to maintain the compatibility correctly.