Preview when shared — technical reference

This page describes the markup, where the values come from, the output, the administration surface and the extension point. For an introduction see Overview.

The syntax component recognises two equivalent notations of the same block; the same reader evaluates both. The block produces no visible output — it is read while the page metadata is built and takes effect only in the page head.

<og>
title = ...
description = ...
image = :wiki:logo.png
type = article
</og>

%%{{wk:og>title=...|description=...|image=:wiki:logo.png}}%%

type is a special case: the markup accepts any value, including profile or book; the setting for the default type knows only article and website.

Every value may carry several languages in one field, separated by |, each as a two-letter code and a colon. The same applies to the settings defaultDescription, defaultImage and siteName.

<og>
title = de:Kryptographie|en:Cryptography|sl:Kriptografija
</og>

Later values win, empty values never overwrite. What is delivered is whatever is not empty. An empty value produces no tag — deliberately: a delivered empty tag is read by a consumer as a promise that this page has no description, instead of looking for one itself.

The description is the only value whose default is itself a chain: first the page abstract, else the setting defaultDescription, else the wiki tagline.

The order is the point. The abstract comes first because it alone describes the page being shared; default text and tagline describe the wiki and are the same on every page. Without that first stage the commonest case — a page with no block of its own — would deliver no description at all.

The abstract is cut to 200 characters at a word boundary. The value sits deliberately between the roughly 160 characters search engines display and the roughly 300 Open Graph consumers accept — so that one text serves both without two being maintained.

An image value beginning with : is a DokuWiki media ID, not a finished address. It is translated into an absolute URL before delivery — a network fetching the preview has no wiki context and could not resolve an ID.

Delivered are og:title, og:description, og:image, og:url, og:type and og:site_name, plus the twitter: equivalents for title, description and image. Each tag only when its value is not empty.

The screen lives at ?do=admin&page=wkopengraph. It shows the defaults with their effect, offers a page block as a form, and checks the preview images.

The defaults live in the wiki configuration. The form writes them through the ordinary configuration-manager path — there is no second store and no file only this package knows about.

The settings govern the default text, default image, default type, the site name and the thresholds of the image check. An invalid value is not taken over; the default applies instead.

The check reports preview images that are too small or have an unhelpful aspect ratio. It is a report, not a barrier: an image is never withheld, only named.

Other packages contribute their own values through the WKOPENGRAPH_VALUES event. That is stage 3 of the origin. A contributor supplies values only; the vocabulary, the escaping and the decision which tags exist stay with this package — two packages writing into the same head would produce duplicate properties, which consumers resolve inconsistently. Blog, for instance, feeds every post with its own values.

• A page with no block still gets all six values — from the defaults.
• An empty value in the block does not overwrite; it leaves the default standing.
• An unknown key is valid and has no effect.
• Without wkcore the second notation is absent; the first remains.

A preview image should be at least 1200 × 630 pixels and close to a 1.91:1 ratio — the format the common networks show without cropping. Smaller images are delivered, but are often scaled up or dropped.