feat: create sitemap generator

[araujogui]

Description

Create sitemap.xml generator

Validation

Related Issues

Fixes #255

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.

[vercel]

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

Project	Deployment	Review	Updated (UTC)
api-docs-tooling	Ready	Preview	Dec 27, 2025 3:06pm

[codecov]

Codecov Report

❌ Patch coverage is 68.49315% with 46 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.00%. Comparing base (9ddf8f9) to head (71b6c24).
⚠️ Report is 12 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/generators/sitemap/index.mjs	44.15%	43 Missing ⚠️
...enerators/sitemap/utils/createPageSitemapEntry.mjs	78.57%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #520      +/-   ##
==========================================
+ Coverage   79.58%   80.00%   +0.41%     
==========================================
  Files         120      127       +7     
  Lines       12056    12282     +226     
  Branches      841      866      +25     
==========================================
+ Hits         9595     9826     +231     
+ Misses       2458     2453       -5     
  Partials        3        3              

☔ 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.

[avivkeller]

Thanks! I know this is a draft, but a few notes that I thought I might share.

These aren't blockers or concerns, just little notes.

[ovflowd]

@araujogui is this ready for review?

[araujogui]

@araujogui is this ready for review?

Not yet, I still need to implement: #520 (comment)

[Copilot]

Pull request overview

This PR implements a sitemap.xml generator to improve SEO for Node.js API documentation by ensuring search engines can properly index the latest API pages. This addresses issue #255, which identified that missing sitemaps could cause search engines to show outdated information.

Key changes:

• Created a new sitemap generator that depends on the metadata generator
• Added sitemap template with standard XML structure
• Registered the generator in the public generators list

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
src/generators/sitemap/index.mjs	Main generator implementation that creates sitemap.xml with URL entries for all API pages and a main API index page
src/generators/sitemap/template.xml	XML template for the sitemap structure following the sitemap.org protocol
src/generators/index.mjs	Registered the sitemap generator in the publicGenerators export

Comments suppressed due to low confidence (1)

src/generators/sitemap/index.mjs:85

• The sitemap generator lacks test coverage. Consider adding tests to verify the correct generation of sitemap.xml content, including URL construction, filtering of entries by depth, date formatting, and proper XML structure. Tests should also cover edge cases such as empty entry lists and entries with special characters in URLs.

  async generate(entries, { output }) {
    const lastmod = new Date().toISOString().split('T')[0];

    const apiPages = entries
      .filter(entry => entry.heading.depth === 1)
      .map(entry => {
        const path = entry.api_doc_source.replace(/^doc\//, '/docs/latest/');
        const url = new URL(path, BASE_URL).href;

        return {
          loc: url,
          lastmod,
          changefreq: 'weekly',
          priority: '0.8',
        };
      });

    apiPages.push({
      loc: new URL('/docs/latest/api/', BASE_URL).href,
      lastmod,
      changefreq: 'daily',
      priority: '1.0',
    });

    const template = await readFile(
      join(import.meta.dirname, 'template.xml'),
      'utf-8'
    );

    const urlset = apiPages
      .map(
        page => dedent`
        <url>
          <loc>${page.loc}</loc>
          <lastmod>${page.lastmod}</lastmod>
          <changefreq>${page.changefreq}</changefreq>
          <priority>${page.priority}</priority>
        </url>
      `
      )
      .join('\n');

    const sitemap = template.replace('__URLSET__', urlset);

    if (output) {
      await writeFile(join(output, 'sitemap.xml'), sitemap, 'utf-8');
    }

    return sitemap;
  },
};

---

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

[ovflowd]

nit: use template files for this and then do simple key->value substitution. Or use proper rss/feed libraries OR xml libraries.

[avivkeller]

Or use proper rss/feed libraries OR xml libraries.

You can probably use hast (but I'm also fine with it this way), seeing as the majority of it is a template

[araujogui]

If we use hast, we are probably going to need https://github.com/syntax-tree/hast-util-to-xast too

[ovflowd]

I'm fine with whatever that uses the least amount of dependencies. We can also just use yet another template file, we can also simply use another dependency, like the xast one, or rss/feeds or whatever.

[ovflowd]

nit: assign const { href: loc } = new URL('/docs/latest/api/', BASE_URL)

easier to read imo.

[ovflowd]

nit: this should be also another template string coming from a file.

[ovflowd]

nit: no need to assign const htmlPath just return new URL();

Also instead of using new URL() on all these places, could you use URL.parse please?