Expand meta tags for better social media card support

[StevenClontz]

Re: https://groups.google.com/g/pretext-dev/c/pTX_B_EDLWc/m/m7vTCxulBQAJ

[rbeezer]

Quick visual pass. More in a bit. One question: why change "title-plain" to "title-full". I think the latter will get markup (like emphais and math), and that cannot become the value of an attribute (@content). Correct me if I mis-understand, I've not looked too hard.

[StevenClontz]

I posted sample output at https://clontz.org/assets/20260407/ (all CSS etc. is broken, I just posted the single HTML file)

Here's what I get for the Bluesky card (as expected):

Now that image isn't super high quality. I dunno if there's a better canonical image for a pretext document besides the brand-logo, or if we should use/recommend higher-quality/resolution brand logos for this purpose.

[StevenClontz]

Quick visual pass. More in a bit. One question: why change "title-plain" to "title-full". I think the latter will get markup (like emphais and math), and that cannot become the value of an attribute (@content). Correct me if I mis-understand, I've not looked too hard.

Was just messing around and didn't remember to change this back. It's now reverted.

[StevenClontz]

(note: SVGs do not work with BlueSky at least, so another recommendation would be to use a high-quality JPG or PNG...)

[rbeezer]

I'm on a kick with using Claude Code as an assistant. Looks like there might be some useful things to consider in its review. Next comment.

[rbeezer]

Summary: Expands the existing OpenGraph <meta> tags to also emit Twitter/X card meta tags, adds og:title, og:description, and twitter:card, and uses docinfo/blurb (already in the dev schema for Runestone) as the description source with subtitle as fallback.

Issues:

1. blurb is dev-schema only. The blurb element is defined in pretext-dev.rnc (for Runestone's shelf categorization), not the main schema. This PR repurposes it for social metadata. That's fine conceptually, but it means authors using the stable schema will get validation errors if they add <blurb> to their docinfo. Should blurb move to the main schema, or should the PR note this dependency?

2. Significant code duplication. The og and twitter calls for title, image, image:alt, and description are nearly identical — differing only in the attribute name (property vs name). The social-meta-element template already handles both via separate $property and $name params, but each caller duplicates the full block. A loop or a wrapper template that emits both at once would halve the code.

3. Title logic is inconsistent. The subtitle is appended to the title only when $docinfo/blurb exists (<xsl:if test="$docinfo/blurb and $document-root/subtitle">). This means: blurb + subtitle → title is "Title: Subtitle", description is blurb. No blurb + subtitle → title is just "Title", description is subtitle. The subtitle disappears from both when there's no blurb. Should the subtitle always appear in the title regardless of blurb?

4. summary_large_image without guaranteed image. The Twitter card type is unconditionally set to summary_large_image, but the image tag is only emitted when $b-has-baseurl and $docinfo/brandlogo. Without an image, summary_large_image will render poorly — Twitter shows a blank image area. Should fall back to summary when there's no image.

5. Hard-coded "Document Logo" alt text. The og:image:alt and twitter:image:alt use the literal string "Document Logo". This isn't localizable and isn't descriptive. The brandlogo element doesn't currently carry alt text, so there may not be a better source, but worth noting.

6. Empty comment. Line with just <!-- --> (the one before "image") — looks like an editing artifact.

7. article:author may not work as expected. The OGP article spec defines article:author as a URL (profile page), not a name string. Passing personname as the content won't produce useful results for Facebook's parser. The book:author property has the same issue but was pre-existing.

Minor: The seven incremental commits ("first pass", "fix xsl:if", etc.) could be squashed before merge for a cleaner history.

Claude Opus 4.6, acting as a review assistant for Rob Beezer

[rbeezer]

(1) is not important, and of course, I would squash everyting just as part of my routine.

[StevenClontz]

3. Title logic is inconsistent. The subtitle is appended to the title only when $docinfo/blurb exists (<xsl:if test="$docinfo/blurb and $document-root/subtitle">). This means: blurb + subtitle → title is "Title: Subtitle", description is blurb. No blurb + subtitle → title is just "Title", description is subtitle. The subtitle disappears from both when there's no blurb. Should the subtitle always appear in the title regardless of blurb?

😶

No blurb + subtitle → title is just "Title", description is subtitle.

The subtitle disappears from both when there's no blurb.

C'mon Claude, get your act together. 😅

[StevenClontz]

b867072 fixes up 2&4&6, the others are hallucinations or wontfix.