Update project documentation

.github/copilot-instructions.md

@@ -6,6 +6,7 @@
 - Do not use `phpunit` There are missing dependencies that make it fail.
 - Use `php -l <file>` to check for syntax errors.
 - Consider The official documentation for writing dokuwiki plugins: https://www.dokuwiki.org/devel:plugins
+- Whenever necessary, update the README file to reflect new features or changes.
 
 
 # General instructions

README

@@ -1,49 +1,206 @@
-luxtools plugin for DokuWiki
+luxtools (DokuWiki plugin)
+=========================
 
-Lists files matching a given glob pattern.
+luxtools is a suite of tools designed to integrate the host file system with
+DokuWiki, intentionally sidestepping the built-in MediaManager for specific
+workflows.
 
-All documentation for this plugin can be found at
-https://www.dokuwiki.org/plugin:luxtools
+This is a personal project that models my specific workflows and preferences.
+It is likely unsuited for wider adoption without modification.
 
-If you install this plugin manually, make sure it is installed in
-lib/plugins/luxtools/ - if the folder is called different it
-will not work!
 
-Syntax:
-	{{files>...}}
+Related projects
+----------------
 
-Scratchpad (shared, file-backed, no page revisions):
-	{{scratchpad>...}}
+- luxtools-client: https://git.luxick.de/luxick/luxtools-client
+	A client application for direct integration with the client machine
+	(e.g. opening folders/paths from within the browser).
+- luxtools-template: https://git.luxick.de/luxick/luxtools-template
+	A DokuWiki template designed to complement the features of this plugin.
 
-The scratchpad is resolved via the "scratchpad_paths" setting.
 
-Each scratchpad entry is a full filesystem path to a file (including extension),
-followed by an alias line that defines the pad name used in the wiki.
+What this plugin does
+---------------------
+
+luxtools provides DokuWiki syntax that:
+
+- Lists files from configured host filesystem roots (glob pattern)
+- Lists a directory's direct children (files + folders)
+- Renders an image thumbnail gallery (with lightbox)
+- Provides "open this folder/path" links for local workflows
+- Embeds file-backed scratchpads with a minimal inline editor (no wiki revisions)
+
+It also ships a small file-serving endpoint (lib/plugins/luxtools/file.php) used
+to deliver files and generate/cached thumbnails.
+
+
+Important security note
+-----------------------
+
+The file-serving endpoint is designed for convenience and caching and does NOT
+apply DokuWiki ACLs. Anything reachable through a configured root may be
+accessible to anyone who can access your wiki and guess/copy the generated URLs.
+
+Only configure roots that contain non-sensitive data, or protect access on the
+webserver/network level.
+
+
+Installation
+------------
+
+Install like any other DokuWiki plugin.
+
+If you install this plugin manually, make sure it is installed in:
+
+	lib/plugins/luxtools/
+
+If the folder is called differently, DokuWiki will not load it.
+
+
+Configuration
+-------------
+
+luxtools is configured via its dedicated admin page:
+
+	Admin -> Additional Plugins -> luxtools
+
+Key settings:
+
+- paths
+	Allowed base filesystem roots (one per line). Each root can be followed by:
+	- A> /Alias/     (optional) alias used in wiki syntax and open links
+	- W> https://... (optional) web base URL used for links instead of file.php
+
+	Example:
+
+		/srv/share/Datascape/
+		A> /Scape/
+		W> https://files.example.example/Datascape/
+
+	If no W> line is configured, luxtools links will use the plugin endpoint:
+
+		lib/plugins/luxtools/file.php?root=...&file=...
+
+- scratchpad_paths
+	Scratchpad file map (one file path per line, followed by an A> alias line).
 
 	Example:
 		/var/lib/dokuwiki-scratchpads/startpad.txt
 		A> start
 
-Then use:
+- defaults
+	Default inline options appended to each listing call.
+
+- extensions
+	Comma-separated list of file extensions allowed in listings.
+	Leave empty to allow all.
+
+- thumb_placeholder
+	MediaManager ID used as a placeholder image in the gallery (optional).
+
+- gallery_thumb_scale
+	Multiplier for generated thumbnails (1 = 150x150, 2 = 300x300), while still
+	displaying them as 150x150. Useful for HiDPI screens.
+
+- open_service_url
+	URL of a local client service used by {{open>...}} and directory links.
+	See luxtools-client.
+
+
+Features and usage
+------------------
+
+1) List files by glob pattern
+	```
+	{{files>/Scape/projects/*&style=list}}
+	{{files>/Scape/projects/*&style=table&tableheader=1&showsize=1&showdate=1}}
+	{{files>/Scape/projects/*&recursive=1&sort=mtime&order=desc}}
+	```
+
+	Notes:
+	- Pattern matching is performed per-directory (safe glob via fnmatch).
+	- A directory can have a title file (default: _title.txt) to override the
+		displayed folder name.
+
+2) List a directory (folders + files) as a table
+	```
+	{{directory>/Scape/projects/&tableheader=1&foldersfirst=1&sort=name}}
+	```
+	This always renders as a table. It includes an "Open Location" link above the
+	table when rendered as XHTML.
+
+3) Image gallery with thumbnails + lightbox
+	```
+	{{images>/Scape/photos/2025/*}}
+	{{images>/Scape/photos/2025/*&recursive=1}}
+	```
+	Clicking a thumbnail opens a lightbox viewer. Thumbnails are generated and
+	cached via the plugin endpoint.
+
+4) Open a local path/folder (best-effort)
+	```
+	{{open>/Scape/projects|Open projects folder}}
+	{{open>/home/me/notes|Open local folder}}
+	{{open>file:///home/me/notes|Open via file://}}
+	```
+	Behaviour:
+	- Prefer calling the configured local client service (open_service_url).
+	- Fall back to opening a file:// URL in a new tab (often blocked by browsers).
+
+5) Scratchpads (shared, file-backed, no page revisions)
+	```
 	{{scratchpad>start}}
+	```
+	Scratchpads render the referenced file as wikitext and (when you have edit
+	rights on the host page) provide an inline editor that saves directly to the
+	backing file.
 
-Please refer to http://www.dokuwiki.org/extensions for additional info
-on how to install extensions in DokuWiki.
 
-Development deploy helpers:
+Inline options reference (files/images/directory)
+-------------------------------------------------
+
+The listing syntaxes accept options appended with &key=value:
+
+| Option | Values | Notes |
+|---|---|---|
+| recursive | 0\|1 | Recurse into subdirectories. |
+| sort | name\|iname\|ctime\|mtime\|size | Sort key. |
+| order | asc\|desc | Sort order. |
+| foldersfirst | 0\|1 | Group folders before files (useful for tables). |
+| titlefile | _title.txt | Directory title override file name. |
+| cache | 0\|1 | 0 disables page caching (default). |
+| randlinks | 0\|1 | Adds a cache-busting query parameter based on mtime. |
+| showsize | 0\|1 | Show file size (where supported). |
+| showdate | 0\|1 | Show last modified date (where supported). |
+| listsep | ", " | Separator used in list-style rendering for extra fields. |
+| maxheight | 500 | Container max-height in pixels; -1 disables scroll container. |
+
+Additionally for {{files>...}}:
+
+| Option | Values | Notes |
+|---|---|---|
+| style | list\|olist\|table | Output style. |
+| tableheader | 0\|1 | Render table header row. |
+
+
+Credits / upstream
+------------------
+
+luxtools is a fork of the [DokuWiki Filelist plugin](https://www.dokuwiki.org/plugin:filelist)
+
+Upstream authors and contributors include Gina Häußge and the DokuWiki
+community (Dokufreaks).
+
+This fork keeps the original license (GPL-2) and retains the relevant copyright
+notices in the source.
+
+
+Development helpers
+-------------------
+
 - Linux/macOS: ./deploy.sh
-	- Windows (PowerShell + WSL): .\deploy.ps1
 
-----
-Copyright (C) Gina Häußge, Dokufreaks <gina@foosel.net, freaks@dokuwiki.org>
+License
+-------
 
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; version 2 of the License
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-See the LICENSING file for details
+GPL-2. See COPYING / LICENSE.

lang/en/lang.php

@@ -25,9 +25,9 @@ $lang['saved'] = 'Settings saved.';
 $lang['err_save'] = 'Could not save settings. Please check write permissions for conf/local.php.';
 $lang['err_security'] = 'Security token mismatch. Please retry.';
 
-$lang['paths'] = 'Allowed base paths (one per line or comma-separated).';
+$lang['paths'] = 'Allowed base paths (one per line). Optional: follow a path with A> alias and W> web URL.';
 $lang['scratchpad_paths'] = 'Scratchpad files (one per line). Each file path must include the extension. Use a following A> line to set the pad name used in the wiki.';
-$lang['allow_in_comments'] = 'Whether to allow the files syntax to be used in comments.';
+$lang['allow_in_comments'] = 'Whether to allow luxtools syntax (files/images/directory/scratchpad) to be used in comments.';
 $lang['defaults'] = 'Default options. Use the same syntax as in inline configuration.';
 $lang['extensions'] = 'Comma-separated list of allowed file extensions to list.';
 $lang['thumb_placeholder'] = 'MediaManager ID for the gallery thumbnail placeholder.';

lang/en/settings.php

@@ -1,8 +1,8 @@
 <?php
 
-$lang['paths'] = 'Allowed base paths (one per line or comma-separated).';
+$lang['paths'] = 'Allowed base paths (one per line). Optional: follow a path with A> alias and W> web URL.';
 $lang['scratchpad_paths'] = 'Scratchpad files (one per line). Each file path must include the extension; use a following A> line to set the pad name used in the wiki.';
-$lang['allow_in_comments'] = 'Whether to allow the files syntax to be used in comments.';
+$lang['allow_in_comments'] = 'Whether to allow luxtools syntax (files/images/directory/scratchpad) to be used in comments.';
 $lang['defaults'] = 'Default options. Use the same syntax as in inline configuration';
 $lang['extensions'] = 'Comma-separated list of allowed file extensions to list';
 

plugin.info.txt

@@ -1,7 +1,7 @@
 base   luxtools
-author Gina Häußge, Dokufreaks, luxick
+author luxick 
 email  dokuwiki@luxick.de
 date   2026-01-05
 name   luxtools
-desc   Lists files matching a given glob pattern.
+desc   Integrates host filesystem with DokuWiki (files, directories, images, open links, scratchpads).
 url    https://www.dokuwiki.org/plugin:luxtools