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 filesystem copies only; missing paths are ignored and copy errors are logged without failing the generator.

Overview
Adds config-driven static asset copying to the web generator so folders like assets, public, and static land in the build output alongside generated HTML and bundles.

After HTML, JS chunks, and styles.css are written, generate.mjs calls new copyStaticAssets, which reads pathsToCopy from config. Each entry can be a source path (copied under output using the basename) or a { src → dest } map (dest is relative to output). Directories are copied recursively; files use copyFile with clone-on-write when supported. Missing sources (ENOENT) are skipped silently; other failures are logged.

Default global config now sets pathsToCopy: ['assets', 'public', 'static'], so typical doc image/static folders are copied without extra configuration.

^{Reviewed by Cursor Bugbot for commit 99ac172. 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 12, 2026 3:01am

[codecov]

Codecov Report

❌ Patch coverage is 26.00000% with 37 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.29%. Comparing base (f78dea3) to head (99ac172).

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #753      +/-   ##
==========================================
- Coverage   84.48%   84.29%   -0.19%     
==========================================
  Files         174      175       +1     
  Lines       15634    15684      +50     
  Branches     1387     1388       +1     
==========================================
+ Hits        13208    13221      +13     
- Misses       2416     2453      +37     
  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]

Do we need to check isDirectory()? Won't await cp(src, dest, { recursive: true, force: true }) work on files and folders?

[moshams272]

Yeah, but the automated Cursor Bot previously flagged the use of cp for individual files.

#753 (comment)