88 lines
3.8 KiB
Markdown
88 lines
3.8 KiB
Markdown
# Page Link Feature Specification
|
||
|
||
## Goals
|
||
- Allow linking a Dokuwiki page to a media folder via a stable UUID.
|
||
- Enable the `blobs` alias so plugin syntaxes can use `blobs/*` in place of a concrete path when the page is linked.
|
||
- Keep behavior stable and maintainable; avoid heavy scanning on each page view.
|
||
|
||
## Non-Goals
|
||
- Automatic creation of `.pagelink` files (user must create manually).
|
||
- Automatic selection of which folder to link (user decides by placing `.pagelink`).
|
||
- Cross-page bulk management UI.
|
||
|
||
## Core Concept
|
||
- Each page can have **one** UUID stored in page metadata.
|
||
- A folder is considered linked to the page if it contains a `.pagelink` file whose content matches the page’s UUID.
|
||
|
||
## Data Model
|
||
- Page metadata key: `pagelink` with value `<UUID>`.
|
||
- `.pagelink` file content: a UUID string.
|
||
- Cache mapping file in plugin cache folder: maps UUID → folder path.
|
||
- Cache file format: JSON (human-readable, easy to debug).
|
||
- Cache file name: `pagelink_cache.json`.
|
||
|
||
## UUID
|
||
- UUID is created only via a toolbar button.
|
||
- UUID is created once and stored in metadata.
|
||
- UUID is v4 lowercase.
|
||
- UUID is not shown directly to the user (except for copy-to-clipboard).
|
||
|
||
## UI/UX Behavior
|
||
- Above page content (next to pageid), show link status.
|
||
- If UUID exists and folder is linked: show the linked folder name.
|
||
- If UUID exists but no folder is linked: show a “not linked yet” status.
|
||
- Clicking the status copies the UUID to clipboard for easy `.pagelink` creation.
|
||
- Status text: "Not linked: Copy ID"
|
||
- Copy action does not show anything. No native toasts available
|
||
- If UUID does not exist: no status is shown.
|
||
|
||
## Linking Rules
|
||
- Folder can be moved or renamed; link remains as long as `.pagelink` file stays in that folder.
|
||
- Deleting the `.pagelink` file unlinks the folder.
|
||
- If multiple folders contain the same UUID:
|
||
- Page shows a linked status with the first found folder.
|
||
- Triangle warning icon appears next to folder name.
|
||
|
||
## Search Scope
|
||
- Searches for `.pagelink` files are limited to paths under root aliases defined in `paths` in [admin/main.php](../admin/main.php).
|
||
- New setting `pagelink_search_depth` limits maximum depth under each root path.
|
||
- Example: depth `2` means only folders at most 2 levels deep are searched.
|
||
- Integer value, default `3`.
|
||
- No negative values allowed.
|
||
|
||
## Cache Strategy
|
||
- Mapping of UUID → folder path is cached in a mapping file for performance.
|
||
- On page load:
|
||
1. If page has UUID, check cache for linked folder.
|
||
2. If cache miss, scan folders (within scope) for `.pagelink`.
|
||
3. Update cache with any matches.
|
||
- Cache invalidation strategy:
|
||
- No automatic cache rebuilds.
|
||
- When encountering stale cache entry (moved/deleted folder) while looking for a pages linked folder, remove from cache and rescan.
|
||
|
||
- Cache writes are atomic (write temp + rename) and use `LOCK_EX`.
|
||
|
||
## Performance Constraints
|
||
- Avoid full-tree scans on every page view.
|
||
|
||
## Security & Safety
|
||
- Never scan outside configured root paths.
|
||
- ignore symlinks.
|
||
- Handle unreadable folders/files gracefully (no fatal errors).
|
||
|
||
## Acceptance Criteria
|
||
- Clicking toolbar button sets metadata `pagelink` to a valid UUID.
|
||
- If a matching `.pagelink` exists in a scoped folder, `blobs/*` resolves to that folder.
|
||
- If `.pagelink` is deleted, the link is removed on next lookup and UI reflects “not linked yet”.
|
||
- Cache prevents repeated scans on consecutive page views.
|
||
- Search depth obeys `pagelink_search_depth`.
|
||
|
||
## Edge Cases
|
||
- Page has UUID but `.pagelink` file is empty or invalid UUID.
|
||
- Multiple `.pagelink` files with same UUID in different folders.
|
||
- UUID in metadata is malformed.
|
||
- Folder contains `.pagelink` but no read permissions.
|
||
- Page is deleted/renamed after UUID creation.
|
||
|
||
## Documentation Updates
|
||
- Update README to describe the feature, settings, and manual `.pagelink` workflow. |