feat: assets copying

[moshams272]

Description

Local images referenced in Markdown files were not resolved correctly or copied to the final build, this PR will solve this by copying the images in the output/assets/.

I solved this from root from the jsx-ast phase as they are markdown AST because we can iterate on them easier than JSX elements.

Steps:

• Updated src/generators/ast/generate.mjs to include the absolute fullPath of each Markdown file.

• Updated src/generators/metadata/utils/parse.mjs to include the fullPath into the metadata entries.

• Implemented extractAssetsFromAST in src/generators/jsx-ast/utils/buildContent.mjs, that identifies local images, rewrites their URLs to a centralized /assets/ directory, and collects the source paths.

• Implemented copyProjectAssets to the web generator src/generators/web/generate.mjs to aggregate all unique assets and copy them to the output directory.

Validation

• Added tests in src/generators/jsx-ast/utils/__tests__/buildContent.test.mjs to verify that the assetsMap is populated with absolute paths.

• Tested against Node.js API documentation; local images (like logo.png) are now correctly copied to the out/assets folder and displayed in the web generated.

Related Issues

#748

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run node --run test and all tests passed.
• I have check code formatting with node --run format & node --run lint.
• I've covered new added functionality with unit tests if necessary.

[cursor]

PR Summary

Low Risk
Build-time file copies only; ENOENT is ignored and non-ENOENT errors are logged without failing the generator.

Overview
Adds static asset copying to the web generator so configured source folders land in the build output alongside HTML, JS chunks, and CSS.

A new copyStaticAssets helper reads config.pathsToCopy: string entries copy recursively into output using the source basename; object entries map explicit source→destination paths (leading slashes on destinations are stripped). Missing sources (ENOENT) are skipped quietly; other copy failures are logged.

generate.mjs invokes this step after writing bundles when config.output is set. Default global config now sets pathsToCopy to ['assets', 'public', 'static'], which generators inherit via existing config merging. Unit tests cover string/object mappings, falsy entries, and error handling.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jun 15, 2026 6:17am

[codecov]

Codecov Report

❌ Patch coverage is 98.80952% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.60%. Comparing base (f78dea3) to head (7369ac5).

Files with missing lines	Patch %	Lines
src/generators/web/generate.mjs	33.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #753      +/-   ##
==========================================
+ Coverage   84.48%   84.60%   +0.12%     
==========================================
  Files         174      176       +2     
  Lines       15634    15802     +168     
  Branches     1387     1411      +24     
==========================================
+ Hits        13208    13369     +161     
- Misses       2416     2423       +7     
  Partials       10       10              

☔ View full report in Codecov by Harness.
📢 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.

[avivkeller]

Why can't the user specify "all my assets are in /xyz/, copy that", this seems like a lot of work and data that needs to now be processed

[moshams272]

Why can't the user specify "all my assets are in /xyz/, copy that", this seems like a lot of work and data that needs to now be processed

If you mean as staticDir in the config file, I think when a project uses doc-kit he cann't iterate to put them in one folder!

what do you think?

[avivkeller]

I think when a project uses doc-kit he cann't iterate to put them in one folder!

Say pathsToCopy: [{ '/path/to/my/assets': '/path/to/my/output' }, '/path/to/my/other/asset'] -> Output /path/to/my/assets at /path/to/my/output and /path/to/my/other/asset at asset.

wdyt @nodejs/web-infra I want opinions

[moshams272]

I'll hold off on fixing the bot's comments, Waiting for the final decision.

[bmuenzenmeyer]

I think when a project uses doc-kit he cann't iterate to put them in one folder!

Say pathsToCopy: [{ '/path/to/my/assets': '/path/to/my/output' }, '/path/to/my/other/asset'] -> Output /path/to/my/assets at /path/to/my/output and /path/to/my/other/asset at asset.

wdyt @nodejs/web-infra I want opinions

yeah this is a really common pattern

• https://www.11ty.dev/docs/copy/
• https://docs.astro.build/en/guides/imports/#files-in-public
• https://nextjs.org/docs/pages/api-reference/file-conventions/public-folder

[avivkeller]

@moshams272 We've decided to use the pathsToCopy: [{ '/path/to/my/assets': '/path/to/my/output' }, '/path/to/my/other/asset'] pattern, are you okay doing that?

We think the default should be pathsToCopy: ["assets", "public", "static"] and similar

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

There are 3 total unresolved issues (including 1 from previous review).

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

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

[avivkeller]

other than my previous concern, lgtm

[bjohansebas]

The changes look good to me, but could we add some tests?

[AugustinMauroy]

LGMT !