dorfteich/docs/manual/user-guide.md

# User guide

_Deutsche Fassung: [docs/de/manual/user-guide.md](../de/manual/user-guide.md)_

How to find your way around Dorfteich as a regular member. For pond
configuration see the [pond-admin guide](pond-admin-guide.md); for
instance administration the [site-admin guide](site-admin-guide.md).

## Signing up and signing in

- **Sign up** (if the instance allows open registration): username,
  e-mail, display name, password, language. You confirm your e-mail via
  the link in the verification mail; that also creates your **personal
  pond** — your own space that only you can see until you share it.
- **Sign in** with username _or_ e-mail. Forgot your password? The
  sign-in page has a reset link (requires the instance to have mail
  configured).
- Your sessions are listed under **Settings → Sessions**; you can revoke
  any device from there.

## Ponds and pages

- The **pond switcher** in the top bar moves you between the ponds you
  can see — and **"+ New pond"** at its bottom creates a new shared pond
  (subject to a quota the site admin sets). The **sidebar** lists the pages of the current pond — sort
  them A–Z, by creation date, or drag them into a manual order (the sort
  mode is a pond setting).
- **+ New page** at the bottom of the sidebar creates a page. Page
  addresses are readable: `/p/<pond>/<page>`.
- **Pages form a tree.** A page created while another page is open
  becomes its subpage (the form says so); pages nest up to six levels.
  The sidebar's **folder view** shows the tree with collapsible
  branches; the **label view** groups pages under the label tree
  instead. The toggle above the page list is yours alone — the pond
  owner only sets the default. Moving a page never changes its address,
  so links keep working.
- **Moving pages:** drag a page onto another one to nest it there
  (drag between pages to reorder within the level, in manual sort
  mode), or use **… → Move to…** for a picker that works in any sort
  mode. Deleting a page that has subpages asks what should happen:
  move them up one level, or trash the whole subtree together.
- The **graph** link at the bottom of the sidebar opens the pond's
  **knowledge graph**: pages as dots, wikilinks as lines — click a dot
  to open the page, drag to rearrange, scroll to zoom. Dashed dots are
  wikilink targets that do not exist yet; clicking one creates the
  page. Below each page (read mode) a **local graph** shows its own
  neighborhood, switchable between one and two hops.
- The **trash** link sits at the very bottom of the sidebar: deleted
  pages can be restored from there until the retention period ends.
  A restored page re-attaches to its nearest surviving parent, or to
  the top level when the whole branch is gone. Checkboxes let you
  select several pages (or **select all**) and restore or permanently
  delete them with one click.

## The editor

Click the **pencil icon** in the top bar to switch a page between
reading and editing. In edit mode a toolbar offers paragraph styles
(H1–H4), bold/italic/strikethrough/inline code, bullet/numbered/task
lists, quotes, code blocks, horizontal rules, images, and tables. The
toolbar stays visible while you scroll.

- **Everyone edits together.** Other people on the page appear in the
  presence strip in the top bar and as named cursors in the text.
  There is no save button for content — every keystroke is persisted and
  replicated live.
- **Offline?** The status icon in the footer (bottom left) shows your
  connection. You can keep typing offline; changes sync on reconnect.
- **Markdown in, Markdown out.** You can paste or type Markdown; the
  page can always be copied or downloaded as Markdown again (**…**
  overflow menu → Copy/Download Markdown).
- **Wikilinks:** type `[[page-slug]]` or `[[page-slug|shown text]]`.
  Links to pages that do not exist yet are listed on the pond home page
  ("phantom pages") — one click creates the target. Following such a link
  works too: the page opens with a "this page does not exist yet" notice
  and a button that **creates it right there**, and every link pointing at
  the address starts working. The **backlinks** panel of a page shows
  every page that links to it.
- **Images and attachments:** paste or drag images straight into the
  text. Other file types (PDFs etc., as allowed by the instance) attach
  to the page via the **paperclip icon**.
- **Named versions:** the **save icon** in edit mode stores a named
  snapshot ("before the big rewrite"); `Ctrl/Cmd+S` stores an unnamed
  one, `Ctrl/Cmd+Shift+S` asks for a name — a short toast confirms every
  save. The **history icon** lists all versions — automatic and named —
  with their contributors; you can view any version and restore it.
  Restoring never deletes history.

## The top-bar page actions

When a page is open you find, next to the pencil: **watch** (bell for
this page), **comments** (with unread count), **attachments**,
**plugin tools** (table of contents, page index — when enabled),
**labels**, the **favorite star**, **history**, and the **…** overflow
menu (copy/download Markdown, export to Word/LibreOffice/PDF, move to…,
delete).

## Favorites

Click the **star** in the page actions to mark a page as one of your
favorites — the star fills golden, and the page's icon in the sidebar
tree turns golden too. Favorites are **personal**: your stars are yours
alone and never visible to other members. The **Favorites** button next
to the sidebar's view switch narrows the page list to your favorites
(combinable with the label filter).

## Labels

Open the **label icon** to tag the page. You can pick existing labels or
create one on the spot (creating is for pond admins). Labels organize
pages and can carry access rules — a page inherits every rule of its
labels.

## Search

The search field in the top bar searches every page you are allowed to
read, across all ponds — tolerant of accents ("Baume" finds "Bäume") and
of partial words. Recent searches are remembered (and can be cleared).

## Comments

The **speech-bubble icon** opens the comment panel: threads with one
reply level, Markdown supported, edit and delete for your own comments,
**resolve** to fold finished discussions away. Whether every reader or
only editors may comment is a pond setting.

## Watches, notifications, digests

- **Watch** a page (bell in the page actions) or a whole pond (bell in
  the pond settings header) to be notified about changes and comments.
  By default you automatically watch pages you create or comment on —
  both switches live under **Settings → Profile**.
- The **bell in the top bar** is your notification inbox; entries link
  straight to the change (comment notifications open the panel).
- **E-mail digests** bundle unread notifications hourly or daily —
  configure under Settings, unsubscribe from any digest mail directly.

## Import and export

- **Import a document** (sidebar link): `.docx`, `.odt`, or `.md`
  becomes a new page, embedded images included.
- **Export a page**: overflow menu → Markdown / Word / LibreOffice /
  PDF. **Export a pond**: pond settings → ZIP of all pages you may read,
  as Markdown plus media.

## Your settings (top-right → Settings)

Profile (display name, e-mail, language, watch defaults, digest
frequency), password, active sessions, your watches, **API tokens** (for
scripts and AI assistants — see the [API guide](api-guide.md) and
[MCP guide](mcp-guide.md)), **feed tokens** (read-only, for Atom
feeds of non-public ponds), and **data export**: a ZIP with your profile
data and the full content of your own ponds.

## Public pages

If a pond admin has published a page for the public, it is readable
without an account at `/public/<pond>/<page>` — with the pond's
typography and a link to the instance's legal pages.

## Feeds (Atom)

Every pond has an Atom feed of its recently created and updated pages at
`/api/v1/public/<pond>/feed.xml`, and every page has a feed of its
version history at `/api/v1/public/<pond>/<page>/feed.xml` (issue #149).
Public ponds serve them without an account — public pages also advertise
the pond feed to feed readers. For non-public ponds, create a **feed
token** under _Settings → Feed tokens_ and append it to the URL as
`?token=dt_feed_…` — feed tokens are read-only and only ever
authenticate feeds, never the API.