Document URL parts and rich-text changes in lib-portal (XP 8.1)

[rymsha]

Companion to enonic/xp#12420 (XP 8.1; master port enonic/xp#12395), its follow-ups enonic/xp#12435 and enonic/xp#12437, and enonic/app-guillotine#1542 and enonic/app-guillotine#1558, for XP 8.1.0. Guillotine's docs link here for what each URL component holds, so the anchors #portalscope, #pageurlparts, #imageurlparts, #attachmenturlparts and #processhtmlparts are what it references.

Changes

• docs/libraries/lib-portal.adoc
  • Base URLs gains two subsections:
    • URL parts: the request-following functions and their configuration-only counterparts; the site or project resolved once by portalScope() and passed as scope; how to assemble each URL.
    • URLs that do not resolve: pageUrl(), imageUrl(), attachmentUrl() and processHtml() give a URL answered with 404 and log a warning; processHtmlParts() entries have no parts.
  • New functions: attachmentUrlParts, imageUrlParts, pageUrlParts, processHtmlParts, portalScope, with parameter tables and TypeScript examples taken from the xp examples.
  • New types: PortalScope, PageUrlParts, ImageUrlParts, AttachmentUrlParts, ProcessedHtml, ProcessedHtmlContentLink, ProcessedHtmlAttachmentLink, ProcessedHtmlImage, ProcessedHtmlImageStyle, ProcessedHtmlImageSource, ProcessedHtmlMacro.
  • baseUrl: the base URL of the current site request, with optional params; id, path, project and branch deprecated in favour of portalScope(). The example no longer uses them.
  • pageUrl: project and branch deprecated in favour of pageUrlParts() with a scope from portalScope().
  • processHtml: styles named <application>:<name> or by name alone; macros resolved when processing, an unknown macro left as written; srcset only for images the image API scales, sizes only along with it; imageSrcWidth for the width of the src, also in processHtmlParts.
  • imageUrl / attachmentUrl / pageUrl returns: point to the 404 behaviour. imageUrl names the image types it accepts.
• docs/upgrade.adoc, in the XP 8.1 section: the lib-portal deprecations (before/after) under lib-portal, the Java MacroService.postProcessInstructionSerialize() deprecation under Java APIs, a new Behaviour changes subsection (404 URLs, srcset/sizes, their place after src, rounded image heights, macros), and three entries under Worth adopting, including imageSrcWidth. The intro now says no breaking changes for JavaScript code, since the Java macro instruction no longer executes. The 8.1 lib-portal links to imageUrl()/attachmentUrl() now use their actual anchors (#imageUrl, #attachmentUrl); they did not resolve before.
• New functions, types and behaviour carry the existing 8.1.0 badge.

Verification

Rendered both pages with Asciidoctor (@asciidoctor/cli 4): no new warnings, and every in-page cross-reference of lib-portal.adoc resolves.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L8TCeZWgJjKTDhmntR9JtB

---

Generated by Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

The attachment error contract is contradictory, and two parameter descriptions need correction.

Review effort: Balanced
Findings: 3

Open (3)

• Correct attachmentUrl unknown-name error behavior · New
• Clarify imageWidths as an array of widths · New
• Capitalize HTML consistently · New

What changed in this PR

Documents XP 8.1 URL-part APIs, rich-text processing changes, and migration guidance.

Changes:

• Adds five lib-portal functions and their result types.
• Documents URL assembly, unresolved resources, macros, and responsive images.
• Adds XP 8.1 deprecation and adoption guidance.

File	Description
docs/​libraries/​lib-portal.adoc	Expands the lib-portal reference.
docs/​upgrade.adoc	Adds XP 8.1 migration guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.