From 331e392fc987c175149ccb3fcc964cc8abe7b7bd Mon Sep 17 00:00:00 2001 From: luxick Date: Fri, 9 Jan 2026 10:10:23 +0100 Subject: [PATCH] Convert Readme to markdown --- README | 206 ------------------------------------------------------ README.md | 203 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+), 206 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index 4902eee..0000000 --- a/README +++ /dev/null @@ -1,206 +0,0 @@ -luxtools (DokuWiki plugin) -========================= - -luxtools is a suite of tools designed to integrate the host file system with -DokuWiki, intentionally sidestepping the built-in MediaManager for specific -workflows. - -This is a personal project that models my specific workflows and preferences. -It is likely unsuited for wider adoption without modification. - - -Related projects ----------------- - -- 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. - - -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 - -- 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. - - -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 - -License -------- - -GPL-2. See COPYING / LICENSE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..84c721f --- /dev/null +++ b/README.md @@ -0,0 +1,203 @@ +# luxtools (DokuWiki plugin) + +luxtools is a suite of tools designed to integrate the host file system with +DokuWiki, intentionally sidestepping the built-in MediaManager for specific +workflows. + +This is a personal project that models my specific workflows and preferences. +It is likely unsuited for wider adoption without modification. + + +## Related projects + +- 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. + + +## 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 + ``` + +- **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. + + +## 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 + +## License + +GPL-2. See COPYING / LICENSE.