feat(web): allow JS in template, absolute URL support

[avivkeller]

Ref: nodejs/learn#29

Adds:

• The ability to perform more advanced JS changes in template.html (NOTE: This file is run in the main context. It should be assumed that users TRUST the template.html file they are providing)
• relativeOrAbsolute allows users to specify whether they want doc-kit to generate absolute-style or relative-style URLs

There should be a minimal size-difference to the output bundle

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Apr 4, 2026 8:18pm

[cursor]

PR Summary

Medium Risk
Introduces new Function-based evaluation for template.html and changes link/root URL generation, which can affect rendered output and has security implications if templates are untrusted. Also adjusts search/index URL behavior across the site.

Overview
Enables the web generator’s template.html to use JavaScript template-literal placeholders (${...}) and full JS expressions by evaluating the template at build time, and expands template context to include metadata and the resolved config.

Adds useAbsoluteURLs support to optionally emit absolute internal URLs (based on baseURL), wiring this through page root calculation and UI links/search fetches via a new relativeOrAbsolute helper (with tests).

Fixes Orama DB document href generation to stop stripping the leading slash, and bumps the package version to 1.3.3.

^{Reviewed by Cursor Bugbot for commit f4c6dd9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 92.73743% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.36%. Comparing base (2680e84) to head (f4c6dd9).

Files with missing lines	Patch %	Lines
src/generators/web/utils/processing.mjs	60.00%	12 Missing ⚠️
src/generators/orama-db/generate.mjs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #751      +/-   ##
==========================================
+ Coverage   77.08%   78.36%   +1.27%     
==========================================
  Files         153      156       +3     
  Lines       13749    13918     +169     
  Branches     1111     1146      +35     
==========================================
+ Hits        10599    10907     +308     
+ Misses       3146     3006     -140     
- Partials        4        5       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

orama-db Generator

File	Base	Head	Diff
orama-db.json	8.27 MB	8.28 MB	+9.95 KB (+0.12%)

[Copilot]

Pull request overview

Adds support to the web generator for (1) generating absolute-style URLs based on configuration and (2) evaluating template.html as a JavaScript template literal to allow more advanced template expressions.

Changes:

• Introduces relativeOrAbsolute() utilities (server + UI) and updates UI components/hooks to use them.
• Switches HTML template population to a new Function-based template-literal evaluation and updates the default template.html placeholders.
• Adds tests for relativeOrAbsolute and populateWithEvaluation, and bumps package version.

Reviewed changes

Copilot reviewed 11 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/generators/web/utils/relativeOrAbsolute.mjs	New server-side helper to emit relative vs absolute URLs based on web config
src/generators/web/utils/processing.mjs	Switches HTML rendering to template-literal evaluation; uses relativeOrAbsolute for root URL
src/generators/web/utils/tests/relativeOrAbsolute.test.mjs	Adds unit tests for relative/absolute URL behavior
src/generators/web/utils/tests/processing.test.mjs	Adds unit tests for populateWithEvaluation
src/generators/web/ui/utils/relativeOrAbsolute.mjs	New UI-side helper using #theme/config for URL mode selection
src/generators/web/ui/hooks/useOrama.mjs	Uses relativeOrAbsolute when fetching Orama DB
src/generators/web/ui/components/SideBar/index.jsx	Uses relativeOrAbsolute for navigation link generation
src/generators/web/ui/components/SearchBox/index.jsx	Uses relativeOrAbsolute for search result links
src/generators/web/types.d.ts	Adds useAbsoluteURLs to web generator configuration typing
src/generators/web/template.html	Updates placeholders to ${...} to match template-literal evaluation
src/generators/web/index.mjs	Adds default useAbsoluteURLs: false
package.json	Version bump to 1.3.3
package-lock.json	Lockfile version bump to 1.3.3

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ovflowd]

Introduces new Function-based evaluation of template.html, which can execute arbitrary code if templates are not fully trusted, and changes URL/link generation logic across the site (including search index hrefs), which could break navigation if misconfigured.

I don't like this AT all. Why? Can you properly explain why this is needed? What are we solving that needs this?

[ovflowd]

After looking at the code I see what you're doing, I'm just worried that inline could potentially be eval'd, let's ensure they're never, like this

SGTM!

[avivkeller]

I don't like this AT all. Why? Can you properly explain why this is needed? What are we solving that needs this?

I'd like to pass more data to the template file, like we do here (for example). There are plenty of cases where this is needed, such as when:

1. We want a canonical URL that trims the /index (so we'd supply ${data.path.replace("/index", "")}
2. We want a conditional element (so we'd supply ${data.api === 'my-api' ? "<...>" : "<...>"})

As for eval-ed inline code, that shouldn't happen, as long as the user doesn't wrap it in ${}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit acf914c. Configure here.}