Addressbooks are commonly kept on a CardDAV server, where the individual contacts are represented as single vCard (.vcf) files. Supporting those files as a source format could facilitate integration between ikiwiki and address books, and allow linking wiki entries to people. With the plugin presented here and the calypso server, that is easily possible.

The idea was first presented on DebConf13 by chrysn.

Software involved

  • CardDAV server

    ikiwiki generates its pages from the local file system. Using the calypso CardDAV/CalDAV server makes that trivial, as it stores its contacts as plain files already (and under git version control!).

    The files can be pulled into ikiwiki in the form of an underlay.

  • Rendering VCF files

    A python plugin called vcf has been published in chrysn's plugin repository at git:// It supports contact images (as data: URLs) as well as all the attributes Evolution generates, creates external hyperlinks for those attributes that can be dereferenced (including telephone numbers), and renders vCard categories into ikiwiki tags.

    Python was chosen as a programming language due to the availability of the vobject python module and the author's personal preference.

  • Linking to contacts

    File names of vCard files are usually not usable (4FD53349-51280409-28AD50CB.vcf). To make links like "I've talked to [[John Doe]] about this" possible, the alias directive has to be implemented in the same repository. (Work in progress.)

Issues / Further development

  • The rendered output is currently a plain definition list, and could need some theming and/or grouping.

    The current implementation does not use templating, and instead generates HTML directly in Python (with the help of the MarkupSafe module). Due to the limitations of the foreign language API, ikiwiki's regular templating can't be used anyway.

  • Addresses are rendered by python-vcard builtin address renderer (plus a hack to get unicode out of it), and are not always most beautiful; moreover, this kind of rendering is not themable.

  • The paramlist words in the vcards are plain dumped out after the respective fields. That's unsuitable for theming, and would need localization.

  • In general, the plugin is not internationalized.

  • All VCF pages currently receive a 'Contact' tag. That needs configurability and/or localization. In the same vein, prefix configuration for the category taggings would be useful too.

  • The alias plugin is not ready yet.

  • vCards can not be edited. To be precise: vCards can be edited, but they show vCard sources which are not suitable for user editing. Moreover, the changes would be committed into the wiki main from the underlay, and not travel back.

    Two approaches would make editing feasible, a relatively easy one and a hard-but-wow-if-it-works one:

    • Use a dedicated vCard editing online tool like CardDavMate, which accepts URLs for editing (unlike CardDavMate). Ideally we would even hijack the edit button on vCard pages to take the user to a proper editor.

    • Have a simple edit mask for vCard objects. (It'd be ok if it was incomplete with respect to fields, the vCard format is designed to make that possible). That's related to the structured data issue.

      In such a setup, the vCard list would not go to an underlay, but rather to a git checkout in a subdirectory or a submodule, from which the change could then be pushed back to Calypso. (AFAIK, different git roots are not supported in ikiwiki yet.)

  • Would such a renderer be useful for vCalendar too? (vCard and vCalendar only differ in what they can represent, not in how they do it.)


The setup is currently usable, but just barely so. Once the basic issues are solved (aliases, parameters for tags, enhanced appearence), I will suggest this plugin for inclusion in ikiwiki.

-- chrysn