diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index cf008f2..a86ff2c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -6,6 +6,7 @@ - Do not use `phpunit` There are missing dependencies that make it fail. - Use `php -l ` 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 diff --git a/README b/README index 34dac86..4902eee 100644 --- a/README +++ b/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 +--------------------- -Example: - /var/lib/dokuwiki-scratchpads/startpad.txt - A> start +luxtools provides DokuWiki syntax that: -Then use: +- 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 + +- 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: - - Linux/macOS: ./deploy.sh - - Windows (PowerShell + WSL): .\deploy.ps1 +Inline options reference (files/images/directory) +------------------------------------------------- ----- -Copyright (C) Gina Häußge, Dokufreaks +The listing syntaxes accept options appended with &key=value: -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 +| 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. | -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. +Additionally for {{files>...}}: -See the LICENSING file for details +| 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 + +License +------- + +GPL-2. See COPYING / LICENSE. diff --git a/lang/de/lang.php b/lang/de/lang.php index a1d7cd9..9bf34d0 100644 Binary files a/lang/de/lang.php and b/lang/de/lang.php differ diff --git a/lang/de/settings.php b/lang/de/settings.php index de6e4e4..391fba1 100644 Binary files a/lang/de/settings.php and b/lang/de/settings.php differ diff --git a/lang/en/lang.php b/lang/en/lang.php index 9e6f62b..02f606b 100644 --- a/lang/en/lang.php +++ b/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.'; diff --git a/lang/en/settings.php b/lang/en/settings.php index a511e5d..e439572 100644 --- a/lang/en/settings.php +++ b/lang/en/settings.php @@ -1,8 +1,8 @@ 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'; diff --git a/plugin.info.txt b/plugin.info.txt index ceb2a00..13b2c04 100644 --- a/plugin.info.txt +++ b/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