doc: wrong info + clarification for plugins
Massimo Melina committed
Feb 8, 2026 at 15:36 UTC
c585222d428baf5f60b834ec13cd40c2ee000513
2 files changed
+35
-13
config.md
+1
-1
@@ -63,7 +63,7 @@ Configuration can be done in several ways
63
- `max_kbps_per_ip` throttle output speed on a per-ip basis. Default is Infinity.
64
- `zip_calculate_size_for_seconds` how long should we wait before the zip archive starts streaming, trying to understand its finale size. Default is 1.
65
- `open_browser_at_start` should HFS open browser on localhost on start? Default is true.
66
-- `https_port` listen on a specific port. Default is 443.
66
+- `https_port` listen on a specific port. Default is -1 (disabled).
67
- `cert` use this file for https certificate. Minimum to start https is to give a cert and a private_key. Default is none.
68
- `private_key` use this file for https private key. Default is none.
69
- `allowed_referer` you can decide what domains can link to your files. Wildcards supported. Default is any.
dev-plugins.md
+34
-12
@@ -94,7 +94,33 @@ Let's first look at the things you can export:
94
95
All the following properties are optional unless otherwise specified.
96
97
-- `description: string` try to explain what this plugin is for. (JSON syntax)
97
+### How to write fields marked *[STATIC JSON]*
98
+
99
+These fields are **statically parsed from source code** (for plugin discovery/update checks), so treat them as JSON literals, not generic JavaScript.
100
+
101
+- Use double quotes for strings and for object keys.
102
+- Do not use single quotes, template strings, variables, function calls, comments, or trailing commas.
103
+- Keep these values in the form `exports.<field> = <valid JSON literal>` (not returned from `init`).
104
+
105
+Examples:
106
+
107
+```js
108
+// valid
109
+exports.description = "My plugin"
110
+exports.repo = "user/repo"
111
+exports.preview = ["https://example.com/p1.png", "https://example.com/p2.png"]
112
+exports.depend = [{ "repo": "rejetto/file-icons", "version": 1 }]
113
+
114
+// invalid for fields marked *[STATIC JSON]* in this doc
115
+exports.description = 'My plugin' // single quotes
116
+exports.repo = SOME_VAR // variable
117
+exports.preview = getPreviewList() // function call
118
+exports.depend = [{ repo: "x", version: 1 }] // non-JSON object key
119
+```
120
+
121
+### The actual list
122
+
123
+- `description: string` try to explain what this plugin is for. *[STATIC JSON]*
124
- `version: number` use progressive numbers to distinguish each release
125
- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed. Mandatory.
126
A single number represents the minimum required version; an array of two defines the min/max supported versions.
@@ -114,11 +140,11 @@ All the following properties are optional unless otherwise specified.
140
- `isTheme: boolean | "light" | "dark"` set true if this is a theme that's not supposed to work together with other themes.
141
Running a theme will cause other themes to be stopped. Missing this, HFS will check if the name of the plugin ends with `-theme`.
142
Special values "light" and "dark" to declare whether the theme is (for example) dark and forces HFS to use dark-theme as a base.
117
-- `preview: string | string[]` one or more URLs to images you want to show before your plugin is downloaded. (JSON syntax)
118
-- `depend: { repo: string, version: number }[]` declare what other plugins this depends on. (JSON syntax)
143
+- `preview: string | string[]` one or more URLs to images you want to show before your plugin is downloaded. *[STATIC JSON]*
144
+- `depend: { repo: string, version: number }[]` declare what other plugins this depends on. *[STATIC JSON]*
145
- `beforePlugin: string` control the order this plugin is executed relative to another
146
- `afterPlugin: string` control the order this plugin is executed relative to another
121
-- `repo: string | object` pointer to a GitHub repo where this plugin is hosted. (JSON syntax)
147
+- `repo: string | object` pointer to a GitHub repo where this plugin is hosted. *[STATIC JSON]*
148
- the string form is for GitHub repos. Example: "rejetto/file-icons"
149
- the object form will point to other custom repo. Object properties:
150
- `web: string` link to a web page
@@ -139,11 +165,7 @@ All the following properties are optional unless otherwise specified.
165
complicated object form to link github, use the string form.
166
Plugins with custom repos are not included in search results, but the update feature will still work.
167
- `changelog: { version: number, message: string }[]` the UI will show only entries with version greater than currently installed.
142
- You can use `md` syntax inside the message. (JSON syntax)
143
-
144
-**WARNING:** All the properties above are a bit special and must go in `exports` only (thus, not returned in `init`) and the syntax
145
-used must be strictly JSON (thus, no single quotes, only double quotes for strings and objects), and must fit one line.
146
-
168
+ You can use `md` syntax inside the message. *[STATIC JSON]*
169
- `init: (api: object) => (void | object | function)` described in the previous section. If an object is returned,
170
it will be merged with other "exported" properties described in this section, so you can return `{ unload }` for example.
171
If you return a function, this is just a shorter way to return the `unload`.
@@ -714,7 +736,7 @@ This section is still partially documented, and you may need to have a look at t
736
- preventable
737
- `login`
738
- parameters: { ctx }
717
-- `logout`
739
+- `logout` called just before the logout is done
740
- parameters: { ctx }
741
- `attemptingLogin` called when the login process starts
742
- parameters: { ctx, username, via? }
@@ -898,7 +920,7 @@ While you may just put a zip on any website, that would require manual installat
920
If you want to appear in the Admin-panel, for easier finding and installation, please do as follows.
921
922
Be sure that you are exporting (not returning) the essential properties, like `apiRequired`.
901
-Find the full list in the [Things a plugin can export](#things-a-plugin-can-export) section, marked with "JSON syntax".
923
+Find the full list in the [Things a plugin can export](#things-a-plugin-can-export) section, tagged *[STATIC JSON]*.
924
925
Suggested method for publishing is to have a dedicated repository on GitHub, with topic `hfs-plugin`.
926
To set the topic go on the repo home and click on the gear icon near the "About" box.
@@ -1139,4 +1161,4 @@ If you want to override a text regardless of the language, use the special langu
1161
- frontend events: loginOk, loginFailed
1162
- api.normalizeFilename
1163
- 12.97 (v0.57.28)
1142
- - HFS.customizeText
\ No newline at end of file
1164
+ - HFS.customizeText