plugins: better docs
Massimo Melina committed
May 14, 2025 at 11:16 UTC
b4504448a1123475fcaac7c91d0c23552fef7f83
1 file changed
+24
-7
dev-plugins.md
+24
-7
@@ -11,6 +11,27 @@ Each plug-in has access to the same set of features.
11
Normally you'll have a plug-in that's a theme, and another that's a firewall,
12
but nothing is preventing a single plug-in from doing both tasks.
13
14
+## Development environment
15
+
16
+The simplest way to develop is to create your folder inside the .hfs/plugins folder, and work there.
17
+Each time you make a change, you'll see it reflected in the running server.
18
+This is probably the easiest form to start with.
19
+
20
+A neater way is to keep it both in the for of github repo and installed plugin.
21
+If you want to do so, have a folder with your github repo in it, *outside* your `.hfs` folder.
22
+As you'll see in the [[Publish your plug-in]] section, you should keep your files inside the `dist` subfolder.
23
+Then you'll need to link it inside the plugins folder.
24
+If you go in your .hfs/plugins folder on linux and mac, and enter
25
+
26
+ ln -s /PATH_TO_YOUR_REPO/dist MY_PLUGIN_NAME
27
+
28
+On Windows it may be something like
29
+
30
+ mklink /d C:\path\to\hfs\plugins\my_plugin C:\my_code\my_plugin\dist
31
+
32
+You'll install your repo so that you can edit the sources and see effects in real-time.
33
+This allows you to continue editing your repo and be ready to commit changes.
34
+
35
## Backend / Frontend
36
37
Plugins can run both in backend (the server) and frontend (the browser). Frontend files reside in the "public" folder, while all the rest is backend.
@@ -758,6 +779,9 @@ You can decide if you want to use some building system/transpiler, but you'll ha
779
780
## Publish your plug-in
781
782
+While you may just put a zip on any website, that would require manual installation.
783
+If you want to appear in the Admin-panel, for easier finding and installation, please do as follows.
784
+
785
Suggested method for publishing is to have a dedicated repository on GitHub, with topic `hfs-plugin`.
786
To set the topic go on the repo home and click on the gear icon near the "About" box.
787
Be sure to also fill the "exports.description" field, especially with words that people may search for.
@@ -768,13 +792,6 @@ This is good way to have a clearer repository name on github, while avoiding bei
792
The files intended to be installed must go in a folder named `dist`.
793
You can keep other files outside.
794
771
-Hint: if you go in your .hfs/plugins folder on linux and mac, and enter
772
-
773
- ln -s /PATH_TO_YOUR_REPO/dist MY_PLUGIN_NAME
774
-
775
-You'll install your repo so that you can edit the sources and see effects in real-time.
776
-This allows you to continue editing your repo and be ready to commit changes.
777
-
795
If you have platform-dependent files, you can put those files in `dist-PLATFORM` or `dist-PLATFORM-ARCHITECTURE`.
796
For example, if you want some files to be installed only on Windows with Intel CPUs, put them in `dist-win32-x64`.
797