# datascape

Minimal self-hosted personal wiki. Folders are pages.

## Features

- **Pages**: a folder's `index.md` renders as HTML, and the folder's other files are listed below it. Going to a missing path lets you create the page there.
- **Editing**: edit the whole page or a single heading's section. Tick task checkboxes directly on the rendered page.
- **Move, rename, delete**: moving a page onto an empty folder offers to merge into it.
- **View settings**: show the file list as a list or thumbnail grid, sorted by name, date, or size. Videos get thumbnails when `ffmpeg` is installed.
- **Search**: find pages by name.
- **Wikilinks**: `[[query]]` or `[[query::label]]`. They open a search, so links still work after a page is renamed. Typing `[[` in the editor suggests page names. Embed files with `![caption](photo.jpg "left")`.
- **Movie import**: create a page from OMDb metadata. Asks once for a free [OMDb API key](https://www.omdbapi.com/apikey.aspx) and keeps it in the browser.
- **Canvases**: [JSON Canvas](https://jsoncanvas.org) boards stored next to a page. See [Canvas](#canvas).
- **Special folders**: a [photo diary](#diary) and a [fitness dashboard](#fitness).
- **Calendars**: Nextcloud calendars mirrored into the wiki. They add events and weight to the diary, and a [maintenance widget](#calendars) to every page.
- **Quick-add bookmarklet**: save the current tab to a wiki page.
- **Companion app**: an optional desktop helper, downloadable from the wiki footer. It opens wiki files in local apps and folders in the file manager.

## Build & run

The wiki binary embeds the companion binaries, so build those first:

```bash
make companion-release                         # once, and after companion changes
go build -o datascape .                        # local
make deploy                                    # QNAP NAS: stripped ARMv7 build, copy, restart
./datascape -dir ./wiki -addr :8080 -user me -pass secret
```

| Flag | Default | |
|------|---------|-|
| `-addr` | `:8080` | Listen address |
| `-dir` | `./wiki` | Wiki root |
| `-cache` | `./cache` | Thumbnail cache |
| `-user`, `-pass` | | Basic auth (omit to disable) |
| `-reindex-interval` | `30m` | Search index rebuild (`0` = off) |
| `-calendars` | `Calendars` | [Calendars](#calendars) folder, relative to `-dir` (empty = off) |
| `-tz` | system | Time zone for calendars and the diary, e.g. `Europe/Berlin` |

## `.page-settings`

Per-folder `key = value` file. The **view** button in the `Files` header sets the first three keys.

| Key | Values (default first) |
|-----|------------------------|
| `view` | `list`, `thumbnail` |
| `sort` | `name`, `modified`, `size` |
| `order` | `asc`, `desc` |
| `type` | `diary`, `fitness`, `calendars` |

## Keyboard shortcuts

All use Alt+Shift.

| Where | Keys |
|-------|------|
| Anywhere | `E` edit (on a canvas: the selected node), `N` new page, `M` move, `F` search, `H` maintenance |
| Editor | `S` save, `1`–`3` heading, `B`/`I` bold/italic, `C`/`K` code/code block, `L` link, `P` wikilink, `G` embed, `U`/`O`/`X` bullet/numbered/task list, `Q` quote, `R` rule, `T` format table, `D`/`W` date (ISO/long), `V` movie, `Y` delete line |

## Canvas

A page can hold any number of canvases: `<name>.canvas` files in its folder, in the [JSON Canvas 1.0](https://jsoncanvas.org/spec/1.0/) format. **CANVAS** in the page actions creates one. Canvases show up in the page's file list. Opening one shows the whole canvas, with no folder tree or sidebar. `?raw` on its URL returns the file itself.

- **Notes** (text nodes) are markdown, rendered like pages: wikilinks, embeds, tables, task checkboxes. Double-click a note to edit it with the page editor, including its toolbar and shortcuts. Esc or a click outside closes the editor. A note left empty is removed.
- **Files** show images, videos and audio. A markdown file or a page (a folder) is shown rendered, and a `#Heading` subpath narrows it to that section. Anything else shows as a link. Paths are relative to the wiki root.
- **Links** show as a card. **Groups** are labelled frames: moving a group moves what is inside it.
- **Connections**: drag from a node's side handle onto another node. Dropping on empty space creates a new note there. Double-click a connection to label it.

| Input | |
|-------|-|
| Drag background / Space+drag / middle drag | Pan |
| Wheel, pinch | Zoom (Shift+wheel pans sideways) |
| Shift+drag background | Select an area |
| Double-click background | New note |
| Double-click node, Enter, Alt+Shift+E | Edit (label, URL or file for non-notes) |
| Drag node / corner handle | Move / resize, snapped to a 10 px grid (Alt: no snap) |
| Arrows | Nudge (Shift: 1 px) |
| Del, Ctrl+Z, Ctrl+Y, Ctrl+D, Ctrl+A | Delete, undo, redo, duplicate, select all |

Changes save automatically. If the file changes elsewhere while a canvas is open, saving stops and asks for a reload instead of overwriting.

## Diary

```
Diary/
  .page-settings         ← type = diary
  2026/
    index.md             ← # 2026, ## 2026-05, ### 2026-05-11 sections
    2026-05-11 Beach.jpg ← photos go under their date's section
```

The year page shows each day's section with its photos. Months and days that are missing (up to today) appear as placeholders with an `[edit]` button. A calendar in the sidebar jumps to any date.

Bookmarkable shortcuts: `<diary>/today/`, `<diary>/this-month/`, `<diary>/this-year/`.

## Fitness

With `type = fitness`, a folder shows weight charts (daily and weekly mean) below its content. The weights come from the calendars with the `weight` role (see [Calendars](#calendars)). Add `weight-goal = 85` to the folder's `.page-settings` to draw a goal line.

## Calendars

```
Calendars/
  .page-settings   ← type = calendars, roles, sync credentials
  Personal.ics     ← one file per calendar
  Gewicht.ics
  …
```

Pages only read these local files and never contact the calendar server. The built-in sync downloads all calendars of a CalDAV calendar home in the background. Or you can put the `.ics` files there yourself.

```
type = calendars

# Roles: file names without .ics
diary = Personal, Feiertage
weight = Gewicht
maintenance = Maintainance

# Sync (Nextcloud)
caldav-url = https://cloud.example/remote.php/dav/calendars/me/
caldav-user = me
caldav-pass = xxxxx-xxxxx-xxxxx-xxxxx-xxxxx
sync-interval = 15m
```

| Key | |
|-----|-|
| `diary` | Events shown under each diary day: all-day first, then by start time |
| `weight` | Titles like `95,6kg`, shown under the diary day's events |
| `maintenance` | Tasks in the header widget (with the number due today) and on the calendars page |
| `caldav-url` | Calendar home. Empty = no sync |
| `caldav-user`, `caldav-pass` | Use a Nextcloud app password (Settings → Security), not the account password |
| `sync-interval` | Default `15m`. `0` = only at startup and with **Sync now** |

Changes apply without a restart. Each calendar is saved as `<display name>.ics`. A download that fails or is not valid iCalendar keeps the old file. Datascape never serves dotfiles, so the password in `.page-settings` cannot be downloaded. It is still in every backup of the wiki folder.

The calendars page lists the maintenance tasks (repeat rule, last date, next date) and the sync status of each calendar.

## Quick-add bookmarklet

Replace `wiki.host` and `/Topics/Bookmarks/` with your host and target page:

```javascript
javascript:(function(){var s=window.getSelection().toString().trim();var t=s||document.title;var u=location.href;var to='/Topics/Bookmarks/';var q='?to='+encodeURIComponent(to)+'&url='+encodeURIComponent(u)+'&title='+encodeURIComponent(t);window.open('https://wiki.host/quickadd'+q,'quickadd','width=480,height=320');})();
```

Each save adds this to the target page's `index.md`:

```markdown
- [Example Page](https://example.com)
  2026-05-11 14:30
  optional comment
```