271 lines
8.6 KiB
Markdown
271 lines
8.6 KiB
Markdown
# 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:
|
||
|
||
```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
|
||
|
||
### 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¢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 (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](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.
|