# 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) - 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/.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: ```bash 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 `` blocks. When editing a page, click the code block button (angle brackets icon `<>`) in the toolbar to wrap selected text in `` 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 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?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¢er|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¢er` 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 (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](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.