sitemap URLs missing extensions when build.format = file

[borisovg]

Astro Info

Astro                    v5.17.2
Vite                     v6.4.1
Node                     v24.13.1
System                   Linux (x64)
Package Manager          pnpm
Output                   static
Adapter                  none
Integrations             @astrojs/sitemap (v3.7.0)

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

Given that astro.config.mjs contains build: { format: "file" } and sitemap integration is used the sitemap has incorrect URL which is missing the file extension.

For example:

$ find dist/
dist/
dist/test.html
dist/sitemap-index.xml
dist/index.html
dist/favicon.ico
dist/favicon.svg
dist/sitemap-0.xml

$ cat dist/sitemap-0.xml 
<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1"><url><loc>https://example.com</loc></url><url><loc>https://example.com/test</loc></url></urlset>

https://example.com/test in the wrong URL

Related: #11575

What's the expected result?

I would expect the sitemap URL to include .html extension (e.g. https://example.com/test.html in my example above).

Link to Minimal Reproducible Example

https://stackblitz.com/github-enn5c2ht

Participation

• I am willing to submit a pull request for this issue.

[borisovg]

Dirty hack workaround:

  integrations: [
    sitemap({
      serialize(item) {
        if (!item.url.endsWith("/")) {
          item.url += ".html";
        }
        return item;
      },
    }),
  ]

[astrobot-houston]

I was able to reproduce this issue. When build.format: 'file' is set with the @astrojs/sitemap integration, the generated sitemap produces URLs like https://example.com/test instead of https://example.com/test.html, even though the built file is dist/test.html. The root cause is that the sitemap integration's URL generation logic in packages/integrations/sitemap/src/index.ts has no specific handling for build.format === 'file' — the route generator produces extensionless paths like /test, and the conditional logic only handles the directory format (adding trailing slashes) while the file format falls through to the default case, pushing the URL as-is without .html.

Fix: I was unable to find a fix for this issue. Investigation revealed this is intended behavior, confirmed by existing tests (packages/integrations/sitemap/test/trailing-slash.test.js:32-52 explicitly asserts URLs without .html) and by two maintainers: natemoo-re (on #7422, 2023: "AFAICT, this output is correct... sitemaps should contain clean URLs") and ematipico (on #11575, 2024: "The one without .html should be the correct one... you want to generate a URL that users want to navigate to"). However, there is a legitimate inconsistency: the Configuration Reference documents that Astro.url.pathname includes .html when using build.format: 'file', and on static hosting without URL rewriting, the extensionless sitemap URLs would 404. This may warrant reconsideration given recurring user feedback (#7422, #11575, #15526). As a workaround, you can use the sitemap integration's customPages option to manually specify URLs with .html extensions, or configure your static host to handle clean URL rewriting.

Priority: [P2: has workaround]. This affects users with build.format: 'file' on static hosting without URL rewriting — the sitemap will contain URLs that 404. However, the behavior is intentional per maintainer decisions, and there are workarounds: using customPages to specify correct URLs, configuring hosting URL rewrites, or switching to build.format: 'directory'. The impact is limited to the specific combination of build.format: 'file' + static hosting without clean URL support.

Full Triage Report

Issue #15526: Sitemap URLs missing extensions when build.format = "file"

Original Issue

• Title: sitemap URLs missing extensions when build.format = file
• Author: borisovg
• URL: sitemap URLs missing extensions when build.format = file #15526
• Created: 2026-02-16T00:57:05Z
• State: OPEN

Description

When astro.config.mjs contains build: { format: "file" } and the @astrojs/sitemap integration is used, the generated sitemap has incorrect URLs that are missing the .html file extension.

For example, the file dist/test.html is generated correctly, but the sitemap contains:

<url><loc>https://example.com/test</loc></url>

Expected Result

The sitemap URL should include the .html extension: https://example.com/test.html.

Environment

• Astro v5.17.2 (issue reporter) / workspace astro (reproduction)
• @astrojs/sitemap v3.7.0 (issue reporter) / workspace @astrojs/sitemap (reproduction)
• Node.js v24.13.1 (issue reporter)
• Output: static
• Adapter: none
• Package Manager: pnpm

Reproduction

Status: REPRODUCED

Steps to Reproduce

1. Create an Astro project with the minimal template
2. Configure astro.config.mjs with:
   • site: 'https://example.com'
   • build: { format: 'file' }
   • integrations: [sitemap()]
3. Create a page at src/pages/test.astro
4. Run astro build
5. Inspect dist/sitemap-0.xml

Actual Result

The sitemap at dist/sitemap-0.xml contains:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" ...>
  <url><loc>https://example.com</loc></url>
  <url><loc>https://example.com/test</loc></url>
</urlset>

The URL https://example.com/test is missing the .html extension.

Expected Result

The sitemap should contain:

<url><loc>https://example.com/test.html</loc></url>

Baseline Verification

With the default build.format (which is 'directory'), the sitemap correctly generates URLs with trailing slashes:

<url><loc>https://example.com/</loc></url>
<url><loc>https://example.com/test/</loc></url>

This matches the generated dist/test/index.html structure and confirms the issue is specific to build.format: 'file'.

Root Cause Analysis

The bug is in the @astrojs/sitemap integration at packages/integrations/sitemap/src/index.ts, lines 131-159.

The routeUrls generation code handles three cases:

if (config.trailingSlash === 'never') {
    urls.push(newUrl);
} else if (config.build.format === 'directory' && !newUrl.endsWith('/')) {
    urls.push(newUrl + '/');
} else {
    urls.push(newUrl);
}

The r.generate() function produces paths like /test (without extension and without trailing slash by default).

When build.format === 'file':

• The trailingSlash is not 'never' (it defaults to 'ignore')
• build.format is not 'directory'
• So the code falls through to the else branch and pushes the URL as-is (without .html extension)

There is no specific handling for build.format === 'file' to append .html to the URLs.

Verification

Verdict: intended-behavior

Confidence: medium

Evidence

1. Explicit test asserting current behavior:

The file packages/integrations/sitemap/test/trailing-slash.test.js:32-52 contains a test case titled "build.format: file" that explicitly asserts sitemap URLs do not include .html extensions:

describe('build.format: file', () => {
    it('URLs do not end with trailing slash', async () => {
        const data = await readXML(fixture.readFile('/sitemap-0.xml'));
        const urls = data.urlset.url;
        assert.equal(urls[0].loc[0], 'http://example.com');
        assert.equal(urls[1].loc[0], 'http://example.com/one');   // no .html
        assert.equal(urls[2].loc[0], 'http://example.com/two');   // no .html
    });
});

2. Maintainer statements confirming intent:

• natemoo-re (on issue sitemap does not respect build.format = "file" #7422, 2023): "AFAICT, this output is correct... I'm not sure if we need another option for the sitemap integration to emit .html extensions? That's a hosting concern that we can't really control."
• ematipico (on issue Sitemap url and Astro.url mismatch with build.format file #11575, 2024): "The one without .html should be the correct one" and "you want to generate a URL that users want to navigate to, and usually users want to have a URL without the html extension."

3. Prior issues closed as "correct":

Issue #7422 was closed by natemoo-re as correct behavior. Issue #11575 was closed by PR #12994, which addressed trailing slash redirects but intentionally did not add .html to sitemap URLs.

Counterarguments

Despite being intended, there is a legitimate inconsistency:

1. Documentation says Astro.url.pathname includes .html when using build.format: 'file'
2. On static hosting without URL rewriting, extensionless URLs would 404
3. Multiple user reports (sitemap does not respect build.format = "file" #7422, Sitemap url and Astro.url mismatch with build.format file #11575, sitemap URLs missing extensions when build.format = file #15526) indicate recurring confusion
4. Another maintainer (matthewp) initially seemed open to changing the behavior on Sitemap url and Astro.url mismatch with build.format file #11575

Related Issues

• Sitemap url and Astro.url mismatch with build.format file #11575 (same bug, closed without fixing sitemap)
• sitemap does not respect build.format = "file" #7422 (same bug, closed as "correct" by maintainer natemoo-re)

This report was made by an LLM. Mistakes happen, check important info.