Convert Readme to markdown
This commit is contained in:
206
README
206
README
@@ -1,206 +0,0 @@
|
|||||||
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.
|
|
||||||
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