Document plugin filesystems

docs/developer/plugins.md

@@ -151,6 +151,38 @@ process foo {
 Refer to the source code of Nextflow's built-in executors to see how to implement the various components of an executor. You might be able to implement most of your executor by simply reusing existing code.
 :::
 
+### Filesystems
+
+Plugins can define custom filesystems, which are used by Nextflow to interact with external storage systems through a single interface (see {ref}`remote-files`).
+
+To implement a custom filesystem, create a class in your plugin that extends [`FileSystemProvider`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/file/spi/FileSystemProvider.html). Implement the `getScheme()` method to define the URI scheme for your filesystem:
+
+```groovy
+import java.nio.file.spi.FileSystemProvider
+
+class MyFileSystemProvider extends FileSystemProvider {
+
+    @Override
+    String getScheme() {
+        return 'myfs'
+    }
+
+    // ...
+}
+```
+
+You can then use this filesystem in your pipeline:
+
+```nextflow
+input = file('myfs://path/to/input/file.txt')
+```
+
+Refer to the `nf-https` module (`XFileSystemProvider`) or `nf-amazon` plugin (`S3FileSystemProvider`) in the Nextflow source code for examples of custom filesystems.
+
+:::{tip}
+Custom filesystems are an advanced type of plugin extension. Before creating a new filesystem, make sure that your use case can't already be supported through an existing filesystem such as HTTP or S3.
+:::
+
 ### Functions
 
 :::{versionadded} 22.09.0-edge

docs/working-with-files.md

@@ -226,6 +226,8 @@ myDir.eachFile { item ->
 
 In general, you should not need to manually copy files, because Nextflow will automatically stage files in and out of the task environment based on the definition of process inputs and outputs. Ideally, any operation which transforms files should be encapsulated in a process, in order to leverage Nextflow's staging capabilities as much as possible.
 
+(remote-files)=
+
 ## Remote files
 
 Nextflow works with many types of remote files and objects using the same interface as for local files. The following protocols are supported: