dorfteich/docs/manual/pond-admin-guide.md

Pond-admin guide

Deutsche Fassung: docs/de/manual/pond-admin-guide.md

What you can configure on a pond you administer. You are a pond admin on your own personal pond and on every pond where you hold the pond_admin role. All of this lives behind the gear icon in the top bar (visible on pond routes when you may modify the pond).

Ponds in one minute

Every member gets a personal pond automatically. Additional shared ponds are created via "+ New pond" at the bottom of the pond switcher in the top bar (or through the API, POST /api/v1/ponds) and are subject to the per-user quota the site admin sets ("additional shared ponds per user", default 0). The creator becomes the pond admin.

Name, description, appearance

• Name and description of the pond.
• Fonts: pick heading/body/code typefaces per pond from the built-in, self-hosted catalog (browse it at /fonts) — they apply to the app view, public pages, and PDF exports.
• Sidebar sort for everyone: A–Z, creation date, or manual order.
• Sidebar view default: the page tree ("folders") or pages grouped under the label tree. Members can still switch their own sidebar locally — the setting only picks the starting point.

Members and roles

The members section manages who is in the pond:

Role	May
reader	read pages (as far as rules allow)
editor	read + write pages, upload files
pond_admin	everything, including settings, members, labels

Member counts are limited by the instance quotas (editors/readers per pond). Personal ponds take members too — that is how you share yours.

Access rules (the fine print)

Beyond plain membership, the access rules section edits grants directly. A grant is: subject (a user, all signed-in users, or the public) + role (reader/editor/pond admin) + scope (whole pond, one label, or one page) + effect (allow or deny).

• Label-scoped rules are the power tool: give the "board" label to the confidential pages and allow only the board members' grant on that label — or deny a label to someone who may otherwise read everything.
• Public pages: an allow, reader, public grant on a page (or a label) publishes it read-only at /public/<pond>/<page>.
• Deny beats allow; reads that are denied look like "not found" (the system never reveals what exists).
• The permission inspector on a page explains the effective result for any user — use it whenever a rule combination surprises you.

Labels

Manage the pond's label tree (create, rename, recolor, nest, move, delete). Deleting a label that is still on pages asks for confirmation. Labels also appear in the page label picker, where creating new ones is reserved for you.

Comments policy

Choose whether all readers may comment or editors only. Existing comments stay readable either way.

Watching the pond

The bell in the pond settings header watches the whole pond — you will be notified about every page change and comment in it.

Plugins

Plugins the site admin has installed with mode optional appear here with a per-pond toggle. Required plugins are always active; disabled ones never show up. (Which plugins exist and what they do: site-admin guide.)

Machine access: API and MCP opt-in

Two separate switches expose this pond to token-based access — both off by default, and both only effective if the site admin has enabled the matching instance switch:

• Public REST API (apiEnabled): scripts and integrations may reach the pond with personal access tokens — with exactly the permissions of the token's owner.
• MCP / AI assistants (mcpEnabled): MCP clients such as Claude Code may reach the pond the same way.

A pond that has not opted in is invisible through those interfaces, even to its own members' tokens.

Import an Obsidian vault

Pond settings → Import an Obsidian vault takes a ZIP of a whole vault and turns it into pages. You choose three things:

• Mount under — the page the vault hangs below (or the top level).
• Additional labels — assigned to every imported page, on top of the labels made from the vault's tags.
• YAML frontmatter — removed, or kept as a code block at the top of the page.

What happens to the vault:

• Folders become pages. Each folder turns into a container page and the notes hang below it, mirroring the vault. Pages nest six levels deep at most; if the vault (plus the mount depth) is deeper, the deepest folder levels are merged into one page titled like/this.
• [[Wikilinks]] keep working. Obsidian links point at note names, Dorfteich links at page addresses, so every link is rewritten to the address the note actually got — including [[Note|shown text]], [[Note#Heading]] (the heading part is dropped), and [[folder/Note]]. Links to notes that are not in the vault become missing-page links, exactly as if you had typed them. When two notes in different folders share a name, a plain [[Name]] resolves to the one whose vault path comes first alphabetically.
• Tags become labels. Both tags: in the frontmatter and #tags in the text (which are removed from the text). Nested tags like #status/active become a label hierarchy.
• Images and files come along. Images referenced by a note (![[image.png]] or ![](media/image.png)) become pond files shown in the page; other allowed file types become attachments. They count against the pond's storage quota. ![[Another note]] embeds become plain links (Dorfteich does not transclude pages).

Limits: the ZIP may be up to 64 MiB, and 256 MiB unpacked. An import is all-or-nothing — if anything fails (a full pond, a broken archive), nothing is left behind and you can simply try again.

Files

The file manager lists the pond's uploads with their usage (which page references them) and lets you delete orphans. Storage counts against the pond's quota; the current usage is shown.

Export and deletion

• Export: the whole pond as a ZIP of Markdown files plus media.
• Delete pond: the danger section at the bottom of the pond settings moves a shared pond to the site-level trash (type the pond name to confirm); a site admin can restore it. Your personal pond cannot be deleted — it is your account's home.