luxtools-plugin/README.md

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.

Note on security

The file-serving endpoint (lib/plugins/luxtools/file.php) runs inside DokuWiki and enforces access via per-page ACL: the requester must have at least read access to the wiki page that rendered the link.

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.

Project structure (developer notes)

This repository follows DokuWiki's plugin conventions at the top level (e.g. syntax.php, conf/, lang/, endpoints like file.php).

Reusable PHP code lives in src/ and is loaded via autoload.php. When adding new internal classes under the dokuwiki\plugin\luxtools\ namespace, place them in src/<ClassName>.php.

JavaScript is split into small modules under js/ and registered via action.php so DokuWiki loads them in order.

IDE support (developer notes)

This plugin extends and uses DokuWiki core classes (for example dokuwiki\Extension\ActionPlugin, dokuwiki\Extension\SyntaxPlugin, renderers, handlers). If you only open the plugin folder in your IDE, those types may show as “unknown”.

DokuWiki does not currently ship an official PHP “SDK”/stub package for IDEs. The most reliable way to get full type navigation and autocomplete is to have the DokuWiki sources available in your workspace.

Two recommended setups:

Option A: Add DokuWiki as a git submodule (recommended for a single-folder workspace)

From the plugin root:

git submodule add https://github.com/dokuwiki/dokuwiki.git _dokuwiki
git submodule update --init --recursive

The repository includes a VS Code config in .vscode/settings.json that points Intelephense at ./_dokuwiki/* so the classes resolve.

deploy.sh excludes _dokuwiki/ to avoid deploying the dev-only checkout.

Option B: Use a separate DokuWiki checkout next to the plugin (recommended if you don’t want submodules)

• Clone DokuWiki into a sibling folder (outside this repo)
• Open a multi-root VS Code workspace with both folders

This avoids changing the git state of the plugin repo, but still gives the IDE access to DokuWiki’s class definitions.

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

  Example:

  /srv/share/Datascape/
  A> /Scape/
  

  luxtools links use the plugin endpoint:

  lib/plugins/luxtools/file.php?root=...&file=...

  The generated URLs also include the current wiki page id (id=...) so file.php can enforce ACLs for the host page.

• 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

0) Editor toolbar: Code block button

The plugin adds a custom button to the DokuWiki editor toolbar for quickly inserting <code> blocks.

When editing a page, click the code block button (angle brackets icon <>) in the toolbar to wrap selected text in <code></code> tags, or to insert an empty code block at the cursor position.

This complements DokuWiki's built-in monospace formatting ('') by providing quick access to HTML code blocks.

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) Single image with caption (imagebox)

{{image>/Scape/photos/picture.jpg|This is the caption}}
{{image>/Scape/photos/picture.jpg?400|Resized to 400px width}}
{{image>/Scape/photos/picture.jpg?400x300|Fixed dimensions}}
{{image>/Scape/photos/picture.jpg?left|Float left}}
{{image>/Scape/photos/picture.jpg?400&center|Resized and centered}}

Renders a Wikipedia-style image box with optional caption. Parameters after ? are separated by &:

• Size: ?200 (width) or ?200x150 (width × height)
• Alignment: ?left, ?right (default), or ?center
• Combined: ?400&left or ?400x300&center

The image links to the full-size version when clicked.

5) 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).

6) 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.

Admin settings

The admin settings page includes a default_tablecolumns option that lets you specify which columns are displayed by default in table-style listings. This is a comma-separated list of column names:

• name – File/folder name (always shown)
• size – File size
• date – Last modified date

Example: name,size,date shows all columns by default.

Credits / upstream

luxtools is a fork of the DokuWiki Filelist plugin.

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.