Astro Pagination URLs with .html: Use paginate({ format })

Do not confuse two different format settings#

Astro has two related but separate controls:

For example, this configuration asks Astro to produce file-shaped output:

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  output: 'static',
5
  build: {
6
    format: 'file',
7
  },
8
});

That setting does not automatically guarantee that every URL returned by a paginated route includes .html. The route generator still needs to produce links that the deployed host can resolve.

Conversely, adding .html to a pagination URL does not turn directory output into file output. Change the two settings as a pair only when the deployment contract requires it.

Add the callback to the paginated route#

Suppose the route is src/pages/blog/[page].astro and the site uses static file output:

1
---
2
import type { GetStaticPathsOptions } from 'astro';
3

4
const posts = [
5
  { slug: 'first', title: 'First post' },
6
  { slug: 'second', title: 'Second post' },
7
  { slug: 'third', title: 'Third post' },
8
];
9

10
export function getStaticPaths({ paginate }: GetStaticPathsOptions) {
11
  return paginate(posts, {
12
    pageSize: 2,
13
    format: (url) => url + '.html',
14
  });
15
}
16

17
const { page } = Astro.props;
18
---
19

20
<h1>Page {page.currentPage}</h1>
21

22
{page.data.map((post) => <h2>{post.title}</h2>)}
23

24
{page.url.prev && <a href={page.url.prev}>Previous</a>}
25
{page.url.next && <a href={page.url.next}>Next</a>}

The callback receives the URL Astro computed for that pagination page. Transform that value instead of rebuilding the page number yourself. That preserves Astro’s handling of the first page, the configured base, and any route parameters.

The callback is also useful for a deployment that needs another stable convention:

1
const formatPaginationUrl = (url) => url + '.html';
2

3
return paginate(posts, {
4
  pageSize: 20,
5
  format: formatPaginationUrl,
6
});

Keep the function deterministic. Do not add a query string, locale prefix, or random value unless the deployed route and canonical URL are designed for it.

Verify both the files and the links#

The most useful check is to inspect the built output before debugging the browser:

1
pnpm build
2
find dist/blog -maxdepth 2 -type f | sort
3
rg -n 'blog/[0-9]+(\.html)?' dist/blog

With build.format: 'file', expect a file-shaped result such as:

1
dist/blog.html
2
dist/blog/2.html
3
dist/blog/3.html

The exact first-page path depends on the route shape. What matters is that page.url.next and page.url.prev match files that actually exist in dist/.

Then request the same URLs through the host:

1
curl -I https://example.com/blog.html
2
curl -I https://example.com/blog/2.html
3
curl -I https://example.com/blog/2

If /blog/2.html is 200 and /blog/2 is 404, the callback is required for that host. If both variants work because the server rewrites extensionless paths, you can keep clean URLs, but document the rewrite and test it separately. Do not depend on a local preview that silently supplies routing behavior your static host does not have.

For a Caddy-served static site, compare the generated files, the document root, and the slash or extension policy together. Astro Static Route 404 Behind Caddy covers that host-level boundary.

When not to append .html#

Use the callback only when the public URL contract requires it:

• Keep clean URLs with build.format: 'directory' and a host that serves index.html from each directory.
• Keep clean URLs when a reverse proxy explicitly rewrites /blog/2 to the correct file.
• Append .html when the host exposes the generated files directly and has no extensionless rewrite.
• Do not add .html to an API endpoint or an on-demand route just because a static page uses file output.

If the project is upgrading from an older Astro release, check the installed version before copying the callback. The format option was added to paginate() in Astro 7.1; upgrading the dependency and changing route URLs should be reviewed as one deployment change.

FAQ#