compose_landing_page_jsonld

documenteer.citations.compose_landing_page_jsonld(citations, *, site_url=None)

Compose a site’s citations as a schema.org JSON-LD document, serialized ready to embed in a <script type="application/ld+json"> element.

Parameters:

• citations (Sequence[Mapping[str, Any]]) – The site’s citations, each as the mapping GuideCitation.to_html_context composes and Sphinx’s html_context publishes.

• site_url (str | None, default: None) – The site’s own base URL, used as the url of the self citation’s node.

Returns:

The serialized JSON-LD document, or None when there are no citations — a site that declares none emits no block at all.

Return type:

str | None

Notes

The self citation is the document’s own subject rather than one node among several: this page is that DOI’s landing page, so a consumer reading the document top-level finds the DOI it came for, and the site’s other citations hang off it as schema.org citation values. A site that declares citations but marks none of them self has no such subject, and its citations are emitted as a plain @graph instead.

The returned string is safe to place directly in a <script> element: the characters that could close it early are written as JSON string escapes (see _SCRIPT_ESCAPES), so a title containing </script>, quotes, or ampersands cannot break out of the block.