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 a directory's direct children (files + folders) or files matching a glob pattern
• Renders an image thumbnail gallery (with lightbox)
• Groups multiple {{image>...}} blocks in compact grid/flex layouts
• Provides "open this folder/path" links for local workflows
• Embeds file-backed scratchpads with a minimal inline editor (no wiki revisions)
• Links a page to a media folder via a UUID (.pagelink), enabling a blobs/ alias
• Adds a Page ID download link in the page info area to fetch a .pagelink file
• Renders a basic calendar widget with clickable day links to chronological pages

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.

This plugin uses Composer dependencies shipped inside vendor/. If dependencies are missing in your local checkout, run:

php composer.phar install

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
  

  Notes:

  • Wiki syntax accepts aliases in path form (for example Scape/sub/folder).
  • Open links sent to the local client service are emitted as Alias>relative/path (for example Scape>sub/folder) so each client can resolve its own local root.

  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.

• image_base_path Base filesystem path used for chronological photo integration. On canonical day pages (chronological:YYYY:MM:DD), files that start with YYYY-MM-DD are listed automatically. If a yearly subfolder exists (for example .../2026/), it is preferred.

• calendar_ics_files (REMOVED — replaced by per-slot calendar configuration)

• Calendar Slots (configured via Admin -> luxtools) The plugin supports 4 calendar slots: general, maintenance, slot3, slot4. Each slot has its own settings:

  • File: Local .ics file path
  • CalDAV URL: Remote CalDAV collection URL (optional)
  • Username: CalDAV authentication username
  • Password: CalDAV authentication password
  • Color: CSS color for calendar widget indicators
  • Display: Where to show that slot's calendar indicator (None, Top Left, Top Right, Bottom Left, Bottom Right)

  A slot is enabled if it has a local file path or a CalDAV URL configured. The old calendar_ics_files setting has been replaced by the general slot's file path.

  Default colors:

  • general: #4a90d9 (blue)
  • maintenance: #e67e22 (orange)
  • slot3: #27ae60 (green)
  • slot4: #8e44ad (purple)

• pagelink_search_depth Maximum directory depth for .pagelink discovery under each configured root. 0 means only the root directory itself is checked.

• omdb_apikey OMDb API key used for the movie import toolbar button. The key is sent to the browser for client-side API requests and will be visible in developer tools.

Template style settings

The {{open>...}} links and directory “open” links use a dedicated color placeholder so they can be customized in Template Style Settings.

• Location Links (__luxtools_locationlink__) Default: #b57d35

To be able to customize the color via the UI add the following to your local template style file at conf/tpl/<your-template>/style.ini under the [replacements] section:

__luxtools_locationlink__ = "#b57d35"  ; @ini_luxtools_locationlink

Temporary global input styling

Because the target template is not ready yet, the plugin currently ships a temporary stylesheet that applies @ini_text, @ini_background, and @ini_border to all input, textarea, and select elements site-wide. This file is explicitly marked as a temporary fix and should be removed once the template provides proper form control styles.

Temporary file: temp-input-colors.css

Developer note: DokuWiki serves a combined stylesheet via lib/exe/css.php and caches it. Cache invalidation is based on the mtimes of the source CSS/LESS files. If you deploy into a mounted/remote filesystem with a different clock, preserving mtimes can prevent automatic invalidation (making it look like your CSS changes don't load until you purge cache).

deploy.sh avoids preserving mtimes by default to make CSS iteration smoother. If you explicitly want to preserve mtimes, use:

./deploy.sh --preserve-times

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.

0.1) Editor toolbar: Date Fix

The plugin adds two toolbar buttons for normalizing timestamps while editing:

• Date Fix: Converts the selected timestamp to YYYY-MM-DD (or YYYY-MM-DD HH:MM:SS if time is included).
• Date Fix (All): Scans the whole page and normalizes any recognizable timestamps.

Supported input examples include:

• 2026-01-30
• 30.01.2026
• 30 Jan 2026
• Jan 30, 2026
• 2026-01-30 13:45
• 2026-01-30T13:45:00

0.2) Editor toolbar: Movie Import

The plugin adds a toolbar button for importing movie metadata from the OMDb API.

Setup:

1. Obtain an OMDb API key from https://www.omdbapi.com/apikey.aspx
2. Enter the key in Admin → luxtools under "Movie Import (OMDb)".

Usage:

1. Open a page for editing.
2. Click the movie icon in the toolbar.
3. A prompt appears pre-filled with the first heading from the page (e.g. Project Hail Mary (2026)).
4. Edit the title if needed and confirm.
5. The plugin queries OMDb and inserts a movie metadata block into the editor.

Inserted markup example:

<!-- BEGIN MOVIE -->
{{image>https://...poster.jpg}}
^ Title     | Project Hail Mary |
^ Year      | 2026 |
^ Genre     | Adventure, Drama, Sci-Fi |
^ Director  | Phil Lord, Christopher Miller |
^ Actors    | Ryan Gosling |
^ Plot      | A lone astronaut must save Earth... |
<!-- END MOVIE -->

Re-import behavior: Running the import again replaces the existing movie block (delimited by <!-- BEGIN MOVIE --> / <!-- END MOVIE --> markers) instead of appending a duplicate.

Security note: The OMDb API key is passed to the browser and used for client-side requests. It is visible in browser developer tools and network traffic. This is an intentional tradeoff for this single-user LAN deployment.

0.3) Page Link: link a page to a folder

Page linking uses a page-scoped UUID stored in page metadata. This UUID is used to link the page to a folder that contains a .pagelink file with the same UUID.

The Page Link workflow is driven by the Page ID link in the page info area (page footer, .docInfo):

1. Link Page (page has no UUID yet) Creates the UUID and downloads a .pagelink file.
2. Download Link File (page has UUID, but no linked folder found) Downloads the .pagelink file.
3. Unlink Page (page is linked) Prompts for confirmation, removes the .pagelink file from the linked folder (if found), removes the UUID from the page, and refreshes the page.

After downloading the .pagelink file, place it into the folder you want to link (within your configured paths roots). Once DokuWiki can discover it, the page becomes “linked”.

Once linked, you can use blobs/ as an alias in luxtools syntax on that page, for example:

{{images>blobs/*.png}}
{{directory>blobs/&recursive=1}}

0.4) Calendar widget

Render a basic monthly calendar that links each day to canonical chronological pages:

{{calendar>}}
{{calendar>2024-10}}
{{calendar>2026-03&size=small}}
{{calendar>2026-03&size=large&show_times=0}}

Notes:

• {{calendar>}} renders the current month.
• {{calendar>YYYY-MM}} renders a specific month.
• size=large|small controls the widget layout and defaults to large.
• show_times=1|0 controls inline event times in large mode and defaults to 1.
• Day links target chronological:YYYY:MM:DD.
• Header month/year links target chronological:YYYY:MM and chronological:YYYY.
• Prev/next month buttons update the widget in-place without a full page reload.
• Month switches fetch server-rendered widget HTML via AJAX and replace only the widget node.
• Calendar output is marked as non-cacheable to keep missing/existing link styling and current-day highlighting up to date.
• Small mode keeps the compact day-number-plus-indicator layout.
• Large mode renders inline day events in the month cells and suppresses the corner indicators.
• Only slots whose Display setting is not None participate in widget visibility.
• Indicator placement in small mode is configured per slot via the Display setting.
• Slot colors are reused for both indicators and inline event accents.

0.5) Virtual chronological day pages

When a canonical day page (for example chronological:2026:02:13) does not yet exist, luxtools renders a virtual page in normal show mode instead of the default "page does not exist" output.

The virtual page includes:

• a German-formatted heading (for example Freitag, 13. Februar 2026)
• matching calendar events from all enabled calendar slots (grouped by slot)
• maintenance tasks with completion buttons (from the maintenance slot)
• matching day photos (via existing {{images>...}} rendering) when available

The page is only created once you edit and save actual content.

0.6) Cache invalidation

luxtools provides an admin-only Invalidate Cache action in the page tools menu.

• Purges the entire DokuWiki cache directory (data/cache/*).
• This covers rendered pages, parsed instructions, CSS/JS bundles, and all luxtools-specific caches (thumbnails, pagelink mapping).
• Useful after deploying plugin or template changes (replaces the old touch conf/local.php step in deploy.sh which often failed due to permission errors).
• Also useful when actively adding external photos to the current day page.

0.7) Multi-calendar slot system

The plugin supports 4 calendar slots, each with independent configuration for a local .ics file, CalDAV URL, authentication, and display color.

• general: The default event calendar. Events appear on day pages like before.
• maintenance: A task-oriented calendar. Events are treated as tasks with completion tracking. Tasks can be marked complete/reopened via buttons on day pages.
• slot3, slot4: Reserved for future use. Events from these slots appear on day pages with the slot's label as the section heading.

Calendar data is always read from local .ics files for rendering. If a remote CalDAV source is configured, use the sync feature to populate the local file.

0.8) Maintenance task completion

Maintenance tasks shown on day pages include a "Complete" button. Clicking it:

1. Updates the event's STATUS property in the local .ics file.
2. If the maintenance slot has a CalDAV URL configured, also updates the remote calendar object.
3. Shows visual feedback and reports any remote write failures.

Completed tasks can be reopened with a "Reopen" button.

Write-back rules:

• VEVENT components: STATUS:TODO for open, STATUS:COMPLETED for completed.
• Recurring events: Completion writes an occurrence override/exception to preserve per-occurrence state rather than modifying the master event.

0.9) Event popup

Clicking any event on a day page opens a popup overlay showing:

• Title
• Date/time (formatted in the browser's locale)
• Location (if available)
• Description (if available)
• Calendar slot name

Close the popup by clicking outside it or pressing Escape.

0.10) Maintenance task list syntax

Embed a list of open maintenance tasks anywhere on a wiki page:

{{maintenance_tasks>}}

To limit how far back overdue tasks are shown, add the past setting:

{{maintenance_tasks>&past=14}}

This renders all non-completed maintenance tasks due today or earlier, sorted with overdue tasks first (then by date, time, and title).

The past value is an integer number of days. Overdue tasks older than that window are hidden. The default is 30.

Each task shows its date, optional time, summary, and a "Complete" button.

0.11) CalDAV sync

If a slot has a CalDAV URL configured, the admin panel provides a sync button. Triggering sync downloads all calendar objects from the remote CalDAV collection and merges them into the slot's local .ics file.

Sync can also be triggered from any wiki page using the inline syntax:

{{calendar_sync>}}

The sync button is only visible to admins. Non-admin users see nothing.

Sync is admin-only and does not run automatically. For scheduled sync, see the automatic sync section below.

0.12) Event popup improvements

Clicking an event on a day page or in the calendar widget opens the event detail popup. When the popup is opened from a specific day context (e.g. clicking an event in a calendar day cell), the date is hidden and only the time is shown (since the day is already known).

Clicking empty space inside a calendar day cell opens a day popup listing all events for that day. If there are no events, a "No events" message is shown.

0.13) Event creation

Authenticated users can create new calendar events from the day popup.

1. Click empty space in a calendar day cell to open the day popup.
2. Click "Create Event".
3. Fill in the form: summary (required), date, all-day toggle, start/end time, location, description, and target calendar slot.
4. Click "Save".

The event is written to the local .ics file immediately. If the slot has a CalDAV URL configured, the event is also uploaded to the remote server.

0.14) Event editing

Authenticated users can edit existing calendar events from the event popup.

1. Click an event to open the detail popup.
2. Click "Edit".
3. Modify the fields and click "Save".

For recurring events, editing creates or updates an occurrence override rather than modifying the master event.

Changes are written to the local .ics file first, then pushed to CalDAV if configured.

0.15) Event deletion

Authenticated users can delete events from the event popup.

1. Click an event to open the detail popup.
2. Click "Delete".
3. Confirm the deletion.

For recurring events, you are asked whether to delete:

• This occurrence: Adds an EXDATE to the master event.
• This and future occurrences: Sets an UNTIL date on the RRULE.
• All occurrences: Removes all components with this UID.

Deletion is applied to the local .ics file first, then to CalDAV if configured.

0.16) Automatic sync proposal

Automatic calendar sync is not currently implemented. The recommended approach for a long-lived personal DokuWiki plugin:

Option A: Cron calling the AJAX endpoint (simplest)

*/15 * * * * curl -s -X POST 'https://wiki.example.com/lib/exe/ajax.php' \
  -d 'call=luxtools_calendar_sync&sectok=ADMIN_TOKEN' \
  --cookie 'DokuWikiCookie=SESSION_ID'

Pros: Reuses the existing sync endpoint with no code changes. Cons: Requires a valid admin session cookie and security token, which expire and must be refreshed. Fragile for long-term unattended use.

Option B: CLI script (recommended)

Create bin/calendar-sync.php that boots DokuWiki from the command line, loads the plugin, and calls CalendarSyncService::syncAll() directly.

*/15 * * * * php /path/to/dokuwiki/lib/plugins/luxtools/bin/calendar-sync.php

Pros: No session management, no authentication needed, runs as the web server user. Cons: Requires a small CLI entry point script.

Recommendation: Option B is more robust and maintainable. A CLI script can be as simple as:

<?php
// Boot DokuWiki
define('DOKU_INC', '/path/to/dokuwiki/');
require_once(DOKU_INC . 'inc/init.php');
require_once(__DIR__ . '/../autoload.php');

use dokuwiki\plugin\luxtools\CalendarSlot;
use dokuwiki\plugin\luxtools\CalendarSyncService;

$plugin = plugin_load('action', 'luxtools');
if (!$plugin) { fwrite(STDERR, "Plugin not loaded\n"); exit(1); }

$slots = CalendarSlot::loadEnabled($plugin);
$result = CalendarSyncService::syncAll($slots);
echo $result['ok'] ? "Sync completed.\n" : "Sync completed with errors.\n";

Known limitations

• Recurring event completion write-back: For recurring events, completing a single occurrence writes an override/exception component to the .ics file. This works well for simple RRULE patterns. Some CalDAV servers may handle the override differently. If the override is rejected by the remote server, the local file will still have the correct state, but remote sync may overwrite it on next sync.

• Sync direction: Sync is currently one-directional (remote → local). Local changes (event creation, editing, deletion, task completion) are written back to the remote immediately when CalDAV is configured. However, a full remote-to-local sync may overwrite local changes if the remote still has stale data. The immediate write-back mitigates this in most cases.

• Event creation/editing permissions: Event CRUD operations require an authenticated DokuWiki user. Admin access is not required for event management, only for calendar sync.

1) List files by glob pattern

The {{directory>...}} syntax (or {{files>...}} for backwards compatibility) can handle both directory listings and glob patterns. When a glob pattern is used, it renders as a table:

{{directory>/Scape/projects/*}}
{{directory>/Scape/projects/*&tableheader=1&showsize=1&showdate=1}}
{{directory>/Scape/projects/*&recursive=1&sort=mtime&order=desc}}

Or using the legacy files keyword (same behavior):

{{files>/Scape/projects/*}}
{{files>/Scape/projects/*&tableheader=1&showsize=1&showdate=1}}

Notes:

• Pattern matching is performed per-directory (safe glob via fnmatch).
• Always renders as a table.
• 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|Caption|400}}
{{image>/Scape/photos/picture.jpg|Caption|400x300}}
{{image>/Scape/photos/picture.jpg|Caption|left}}
{{image>/Scape/photos/picture.jpg|Caption|400&center}}
{{image>https://example.com/images/picture.jpg|Remote image caption}}
{{image>https://example.com/images/picture.jpg|Remote caption|400x300&left}}

Renders a Wikipedia-style image box with optional caption. The syntax uses pipe-separated parts:

• {{image>path|caption}} – Image with caption (uses defaults)
• {{image>path|caption|options}} – Image with caption and options

Options (in the third part, 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.

Remote images (HTTP/HTTPS URLs) are linked directly without proxying or thumbnailing.

5) Group multiple image boxes compactly

Use <grouping> ... </grouping> to arrange multiple {{image>...}} entries in less vertical space.

<grouping>
{{image>/Scape/photos/1.jpg|One|300}}
{{image>/Scape/photos/2.jpg|Two|300}}
{{image>/Scape/photos/3.jpg|Three|300}}
{{image>/Scape/photos/4.jpg|Four|300}}
</grouping>

<grouping layout="flex" gap="0" justify="start" align="start">
{{image>/Scape/photos/1.jpg|One|220}}
{{image>/Scape/photos/2.jpg|Two|220}}
{{image>/Scape/photos/3.jpg|Three|220}}
</grouping>

<grouping layout="grid" cols="3" gap="0.4rem">
{{image>/Scape/photos/1.jpg|One|260}}
{{image>/Scape/photos/2.jpg|Two|260}}
{{image>/Scape/photos/3.jpg|Three|260}}
</grouping>

<grouping layout="flex" gap="0.5rem" justify="space-between" align="center">
{{image>/Scape/photos/1.jpg|One|220}}
{{image>/Scape/photos/2.jpg|Two|220}}
{{image>/Scape/photos/3.jpg|Three|220}}
</grouping>

Supported attributes on the opening tag:

• layout: flex (default) or grid
• cols: integer >= 1 (default 2, used by grid)
• gap: CSS length token such as 0, 0.6rem, 8px (default 0)
• justify: start, center, end, space-between, space-around, space-evenly (default start)
• align: start, center, end, stretch, baseline (default start)

Notes:

• The wrapper only controls layout. It adds no own border/background/frame.
• Invalid values silently fall back to defaults.
• Unknown attributes render a small warning string, e.g. [grouping: unknown option(s): gpa].
• Existing standalone {{image>...}} behavior is unchanged outside <grouping>.

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

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

8) Link Favicons (automatic)

External links automatically display the favicon of the linked website. This feature:

• Uses DuckDuckGo's favicon service (icons.duckduckgo.com)
• Works on all external links (class urlextern)
• Shows grayscale icons that become colored on hover
• Browser handles caching; no server-side storage needed

No configuration required. The feature is enabled by default for all external links.

Based on the linkfavicon plugin by Shao Yanmin.

Inline options reference (directory/images)

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).
maxheight	500	Container max-height in pixels; -1 disables scroll container.
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.