Skip to content

DXP-575: Absolute URLs and <img> conversion in generated markdown mirrors - #958

Merged
jmlago merged 3 commits into
mainfrom
legatus/dxp-575
Nov 19, 2026
Merged

jmlago merged 3 commits into
mainfrom
legatus/dxp-575

Conversation

@jmlago

@jmlago jmlago commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Ticket: DXP-575

Context

Most of DXP-575 already shipped in 19558ee ("Optimize docs for LLM navigation"). That commit added per-page .md mirrors generated by scripts/generate-full-docs.js during dev/build, conversion of CustomCard/Card/Image/Callout/Tabs/div/br, a "View as Markdown" button that opens the real .md file instead of a blob URL, and ChatGPT/Claude prompts that send the .md URL. The earlier attempt, #278, was closed without merging.

Two requirements were still open:

  • Absolute URLs: the mirrors kept 200+ relative links such as ](/developers/...), ](./writing-data) and src="/morpheus.png".
  • <img> tags: lowercase <img> leaked through unconverted (e.g. partners/morpheus).

Changes

  • scripts/generate-full-docs.js
    • <img ...> is now converted to a markdown image, the same way <Image> already was.
    • New absolutizeLinks() resolves the targets of markdown links and images, reference-style link definitions, and leftover href/src attributes against the page's URL on https://docs.genlayer.com. It resolves them the same way a browser does (new URL(href, pageUrl)).
    • Fenced code, inline code, mailto: and absolute URLs are left unchanged. Fragment-only links (#section) become <page-url>#section. Angle-bracket destinations ([x]: </path>, [x](</path>)) keep their brackets, and only the URL inside them is resolved.
    • The result applies to the per-page .md mirrors and to every llms-full.txt bundle.
  • scripts/check-llm-exports.js (via findRelativeLink(), which accepts bare and <...> destinations) now fails the build if a relative markdown link (outside code) or a leaked <Image>/<img> appears in the bundles.

Testing

  • npm run test:full-docs (new scripts/test-generate-full-docs.js) → 15 cases: fragment links, root-relative, ./ and ../ links, angle-bracket inline and reference links, images, href, untouched absolute/mailto/code links, and <img> conversion. It also runs every converter output through the build checker's findRelativeLink() to confirm it is accepted, and confirms that relative links, bare or angle-bracketed, are still flagged.
  • node scripts/generate-full-docs.js && node scripts/check-llm-exports.js → OK (225 pages).
  • Ran the new check against the generator from origin/main: it fails with the <img> leak and the relative-link errors. With this change it passes.
  • Spot-checked the output:
    • reading-data.md → https://docs.genlayer.com/developers/decentralized-applications/writing-data
    • deploying.md → .../deploying/cli-deployment
    • morpheus.md → ![Morpheus](https://docs.genlayer.com/morpheus.png)
  • node scripts/test-release-versions.js passes.
  • The Playwright e2e suite (full next build) was not run. Only build-time scripts changed; no components or pages.

Assumptions

  • I kept the existing output location, public/<route>.md (served at <page-url>.md), instead of the ticket's public/pages/. The UI and llms.txt already link to it.
  • I kept the existing callout format, > **Note:** … blockquotes, instead of adding emojis. A text label is at least as clear to an LLM.
  • Relative links are resolved the way a browser would on the live page, with no trailing slash. A few links that are already broken in the source (e.g. docs/validator-guide.md in genlayer-cli.mdx) become absolute but stay broken, same as on the site.
  • The new relative-link check covers the concatenated bundles. The per-page mirrors are built from the same markdown, so it covers them too.

🤖 Generated with Claude Code

Relative links (/foo, ./foo, ../foo) and image paths in the generated .md
mirrors and llms bundles are now resolved against the page URL on
https://docs.genlayer.com, so copied/fetched markdown stays navigable.
Lowercase <img> tags are converted to markdown images like <Image>.
check-llm-exports.js now fails on relative links or leaked <Image>/<img>.

Refs DXP-575

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@netlify

netlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for genlayer-docs ready!

Name Link
🔨 Latest commit 9a8ba50
🔍 Latest deploy log https://app.netlify.com/projects/genlayer-docs/deploys/6afe0a75e8d59dbb70b437da
😎 Deploy Preview https://deploy-preview-958--genlayer-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 27 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e28eeaac-dfcd-426d-91cd-f9ef640db4c0
Commits

Reviewing files that changed from the base of the PR and between 90f98c2 and 9a8ba50.

Files selected for processing: 4

  • package.json
  • scripts/check-llm-exports.js
  • scripts/generate-full-docs.js
  • scripts/test-generate-full-docs.js
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Changes requested (commit b2ff6f1)

  1. P2 — Fragment links remain relative (scripts/generate-full-docs.js:225). Existing links such as [Environments](#environments) in the tooling-setup page remain unchanged in exports. Outside the original document, they cannot identify the source page, contrary to the requirement that all relative URLs become absolute. Resolve fragments against pageUrl and add regression coverage; the new checker explicitly exempts them.

  2. P2 — Reference links with angle brackets are corrupted (scripts/generate-full-docs.js:243). A direct reproduction with [guide]: </validators/setup-guide> produces a URL ending in /developers/intelligent-contracts/%3C/validators/setup-guide%3E. Strip and preserve the Markdown delimiters while resolving the destination, and add a test asserting the correct URL.

Validation: export generation/checks and release-version tests passed. Browser tests could not start because of the existing checker failure below. Audit worktree removed; no push, merge, or GitHub comment performed.

LEGATUS-TICKET
team: DXP
title: Release documentation checker crashes when Python is unavailable
blocks: no
Running npm run test:e2e stops during its build prerequisite at scripts/check-v06-release-docs.js:222 with TypeError: Cannot read properties of null (reading 'trim'). Directly invoking spawnSync("python3", ["--version"]) returns status null, error ENOENT, and stderr null. The same unchecked access exists on origin/main. Expected: an actionable missing-interpreter diagnostic; actual: an uncaught exception before browser tests start.
LEGATUS-END

- #fragment links now resolve to <page-url>#fragment so they still
  identify the source page once exported; the checker no longer exempts them.
- Reference definitions with angle-bracket destinations
  ([x]: </path>) keep their delimiters and resolve the inner URL instead
  of percent-encoding the brackets.
- Add scripts/test-generate-full-docs.js (npm run test:full-docs) covering
  link absolutization and <img> conversion.

Refs DXP-575

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Changes requested (commit b03a2d0)

  1. P2 — Build checker rejects valid absolute angle-bracket links (scripts/check-llm-exports.js:51). The converter correctly produces [Setup](<https://docs.genlayer.com/validators/setup-guide>), but the checker reports it as a relative link and exits 1. I reproduced this by adding the converter’s output to the generated bundles. This breaks dev/build for syntax explicitly supported by the new tests. Handle optional angle delimiters when validating destinations, and add an integration test covering converter output through the checker.

Both previous findings are fixed. test:full-docs, test:release-versions, and checks against the existing generated content passed. Browser tests stopped at the previously reported prerequisite failure below. The audit worktree was removed.

LEGATUS-TICKET
team: DXP
title: Release documentation checker crashes when Python is unavailable
blocks: no
Previously reported issue, reproduced again: npm run test:e2e fails before browser startup at scripts/check-v06-release-docs.js:222 with TypeError: Cannot read properties of null (reading 'trim'). spawnSync("python3", ["--version"]) returns status null, error ENOENT, and stderr null. Expected an actionable missing-interpreter diagnostic; actual result is an uncaught exception.
LEGATUS-END

check-llm-exports.js flagged valid converter output such as
[Setup](<https://docs.genlayer.com/...>) as relative and failed the build.
The check now lives in findRelativeLink(), which unwraps optional <...>
delimiters before validating the destination. The test suite now pipes
every converter case through the checker and asserts relative links
(bare and angle-bracketed) are still caught.

Refs DXP-575

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Approved (commit 9a8ba50)

No merge-blocking findings. All previous findings are resolved, with regression coverage.

Passed: npm run test:full-docs, npm run test:release-versions, export generation/checks, and the previously failing angle-bracket fixture through the actual checker. Browser tests could not start because of the existing issue below. Audit worktree removed; nothing merged or pushed.

LEGATUS-TICKET
team: DXP
title: Release documentation checker crashes when Python is unavailable
blocks: no
Previously reported issue reproduced: npm run test:e2e fails at scripts/check-v06-release-docs.js:222 with TypeError: Cannot read properties of null (reading 'trim'). Invoking spawnSync("python3", ["--version"]) returns status null, error ENOENT, and stderr null. Expected an actionable missing-interpreter diagnostic; actual result is an uncaught exception before browser tests start. This failure is unrelated to the PR.
LEGATUS-END

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

/run-e2e all

@jmlago
jmlago requested a review from danieljrc888 November 18, 2026 20:34
@jmlago
jmlago merged commit e256659 into main Nov 19, 2026
7 checks passed
@jmlago
jmlago deleted the legatus/dxp-575 branch November 19, 2026 01:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant