Convert Readme to markdown
This commit is contained in:
203
README.md
Normal file
203
README.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user