Usage

Usage#

Adding a CardDAV server profile#

  1. Open Settings → Harang Contacts.

  2. Click Add CardDAV server.

  3. Fill in the profile:

Field

Description

Profile name

A label for this server, shown when a contact’s name is ambiguous across servers.

Server URL

The CardDAV base URL, or the exact address book collection URL.

Username / Password

Your CardDAV account credentials.

  1. Click Test connection & auto-discover. The plugin walks the standard CardDAV discovery chain (current-user-principal → addressbook-home-set → address book collection) and fills in the resolved address book URL automatically. If your Server URL already points directly at an address book collection, it is used as-is without further discovery.

You can add multiple profiles (for multiple servers, or multiple address books on the same server); contacts from all of them are merged.

Referencing a contact in a note#

Type {{hrcard: to start a staged reference:

Meeting notes with {{hrcard:

  1. An autocomplete popup lists your registered server profile names; typing narrows it. Selecting one appends <profileName>: and immediately opens the next stage.

  2. The popup now lists that profile’s contacts by name (searched with a case-insensitive substring match), showing each candidate’s organization and email as a hint.

Selecting a contact inserts {{hrcard:<profileName>:<uid>}} and renders it as a chip — the contact’s name, plus their email address if they have one, in a rounded pill. This works the same way in both Live Preview and Reading view.

Note

The inserted syntax stores the server profile and CardDAV UID, not the display name, so the chip always resolves to the exact contact you picked — even if another contact happens to share the same name, and even if their name changes on the server later.

Viewing contact details#

Click a chip to open a small card with the contact’s email, phone, and organization (whichever of those fields the CardDAV record has). Click anywhere outside the card, or press Esc, to close it.

If a chip looks faded with a dashed border, the plugin could not resolve it to a known contact — most often because the address book cache is stale. See Troubleshooting & FAQ.

Refreshing the address book cache#

Contacts are cached and refreshed automatically once the cache lifetime (configurable in settings, default 30 minutes) elapses. To refresh immediately:

  • Run the Refresh contacts command from the command palette, or

  • Click Refresh next to Refresh all address books now in settings.