doc: improved vfs config with examples
Massimo Melina committed
Feb 1, 2026 at 22:04 UTC
25185385ddbc947b3ffd0935ce3ea51498164457
1 file changed
+16
-3
config.md
+16
-3
@@ -137,14 +137,27 @@ Configuration can be done in several ways
137
138
The virtual file system is a tree of files and folders, collectively called *nodes*.
139
By default, a node is a folder, unless you provide for it a source that's a file.
140
+The `vfs` config is a single root node. You can either bind a disk path directly to the root, like so
141
+```
142
+vfs:
143
+ source: /data
144
+```
145
+or expose paths as children of the root:
146
+```
147
+vfs:
148
+ children:
149
+ - source: /data
150
+```
151
+In the first example, the root of HFS shows the contents of `/data`.
152
+In the second example, HFS shows a folder named "data" at the root (name inferred from the path).
153
+
154
Valid keys in a node are:
155
- `name`: this is the name we'll use to display this file/folder. If not provided, HFS will infer it from the source. At least `name` or `source` must be provided.
156
- `source`: absolute or relative path of where to get the content
157
- `children`: just for folders, specify its virtual children.
158
Value is a list and its entries are nodes.
145
-- `rename`: similar to name, but it's from the parent node point.
146
- Use this to change the name of entries that are read from the source, not listed in the VFS.
147
- Value is a dictionary, where the key is the original name. No UI.
159
+- `rename`: when `source` is a folder, you can rename entries *virtually* as they are read from disk.
160
+ Value is a map "original name" → "new name". No UI.
161
- `mime`: specify what mime to use for this resource. Use "auto" for automatic detection.
162
- `url`: when this value is present, the element is a link to the URL you specify.
163
- `order`: a number that you can set if you want to force the position of this element to the top or the bottom of the list.