luxtools-plugin/README

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.