datascape/README.md

# 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.
- **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
GOOS=linux GOARCH=arm go build -o datascape .  # QNAP NAS
./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, `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 |

## 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
```