Paginating a Blog in Astro

Most blog tutorials reach for paginate() — Astro’s built-in helper — and call it done. It works, but the URLs it produces (/blog/2, /blog/3) aren’t great for SEO. Search engines prefer a clear signal that these are pages of a list, not individual resources. /blog/page/2 communicates that explicitly.

This post walks through how I built pagination on this site: clean URLs, no client-side JavaScript, placeholder cards, and a reusable BlogGrid component.

The URL structure

The target structure:

1
/blog           → page 1 (canonical)
2
/blog/page/2    → page 2
3
/blog/page/3    → page 3

Page 1 lives at /blog with no page number — it’s the canonical listing URL and the one that gets linked to from everywhere. Pages 2 and beyond use /blog/page/N to signal clearly that they are paginated continuations.

I deliberately avoided /blog/1 for page 1. A URL like /blog/1 implies there’s a post with the ID 1, or that the canonical URL is somehow different from /blog. Neither is true.

Why not paginate()?

Astro’s paginate() is great for getting started. You export getStaticPaths from a [...page].astro file, pass your content collection and a page size, and Astro generates all the pages. The catch is the URL pattern it produces:

1
/blog           → page 1
2
/blog/2         → page 2
3
/blog/3         → page 3

That flat structure is fine functionally, but /blog/page/2 is more semantically correct and is the pattern recommended by Google for paginated content. To get it with Astro you need to take back control of routing.

Two route files instead of one

Rather than fighting paginate(), I use two separate route files:

src/pages/blog/index.astro handles page 1. It’s a static page — no getStaticPaths needed — that fetches all posts, slices the first page, and renders the grid.

src/pages/blog/page/[page].astro handles pages 2 and above. It uses getStaticPaths to generate one static page per remaining page number.

1
export async function getStaticPaths() {
2
  const PAGE_SIZE = 9;
3
  const allPosts = (await getCollection("posts"))
4
    .filter(isPublished)
5
    .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
6
  const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
7
  return Array.from({ length: totalPages - 1 }, (_, i) => ({
8
    params: { page: String(i + 2) },
9
  }));
10
}

The length: totalPages - 1 is key — page 1 is handled by index.astro, so this file only generates pages 2 through N. Attempting to generate page 1 here would create a conflicting route at /blog/page/1.

isPublished is the same helper from the scheduled publishing post — it filters out drafts and future-dated posts outside of dev mode, so archive pages never leak unpublished content.

Notice that getStaticPaths only returns params, not props. The actual page data — the slice of posts, currentPage, prevUrl, nextUrl — is recomputed in the component script below, using Astro.params.page:

1
const PAGE_SIZE = 9;
2
const currentPage = Number(Astro.params.page);
3

4
const allPosts = (await getCollection("posts"))
5
  .filter(isPublished)
6
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
7

8
const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
9
const posts = allPosts.slice(
10
  (currentPage - 1) * PAGE_SIZE,
11
  currentPage * PAGE_SIZE,
12
);
13
const prevUrl = currentPage === 2 ? "/blog" : `/blog/page/${currentPage - 1}`;
14
const nextUrl =
15
  currentPage < totalPages ? `/blog/page/${currentPage + 1}` : null;

That means the same fetch-sort-slice logic is duplicated three times across index.astro, getStaticPaths, and the component script in [page].astro. It’s a small DRY violation, but getStaticPaths runs in an isolated build-time context before the rest of the file executes, so there’s no way to share the computed allPosts array between it and the component body without a separate module-level helper. For three call sites doing one cheap array operation, the duplication was the simpler trade-off.

A shared BlogGrid component

Both route files render the same grid. Rather than duplicating the markup, I extracted it into src/components/BlogGrid.astro, which accepts these props:

1
interface Props {
2
  posts: CollectionEntry<"posts">[];
3
  currentPage: number;
4
  totalPages: number;
5
  prevUrl: string | null;
6
  nextUrl: string | null;
7
  paginationBase?: string;
8
  sectionLabel?: string;
9
  sectionTitle?: string;
10
  sectionDescription?: string;
11
}

It renders the post grid, placeholder cards, and pagination controls. Both index.astro and [page].astro import it and pass their data through, along with a section label and heading so the same component reads correctly whether it’s showing “Recent articles” on page 1 or “Posts on page 2” further into the archive. paginationBase is what lets the tag system reuse this exact component for paginated tag pages — it swaps /blog/page/N for /tags/<tag>/N without any other change.

Placeholder cards for a half-full grid

While the post count is low, a 9-post grid with only 4 real posts on the last page would look half-empty. Placeholder cards fill the remaining slots instead of leaving obvious gaps.

Click the expand icon to view it fullscreen.

The grid is responsive — two columns on tablet, three on desktop — so a placeholder count that’s correct for one breakpoint can be wrong for the other. BlogGrid.astro computes both independently, then works out how many placeholders are needed at both breakpoints, only one, or neither:

1
const showGhostCards = currentPage === totalPages;
2
const TABLET_COLS = 2;
3
const DESKTOP_COLS = 3;
4
const tabletGhostCount = showGhostCards
5
  ? (TABLET_COLS - (posts.length % TABLET_COLS)) % TABLET_COLS
6
  : 0;
7
const desktopGhostCount = showGhostCards
8
  ? (DESKTOP_COLS - (posts.length % DESKTOP_COLS)) % DESKTOP_COLS
9
  : 0;
10
const sharedGhostCount = Math.min(tabletGhostCount, desktopGhostCount);
11
const tabletOnlyGhostCount = tabletGhostCount - sharedGhostCount;
12
const desktopOnlyGhostCount = desktopGhostCount - sharedGhostCount;

Only the last page ever gets placeholders — every other page is a full row at both breakpoints. The three resulting counts each render into a differently-classed cell (--tablet-up, --tablet-only, --desktop-only) so CSS media queries can show or hide the right ones without any JavaScript recalculating the layout on resize.

I deliberately kept BlogCardPlaceholder.astro static rather than reaching for an animated loading skeleton. These cards aren’t hiding content that’s still loading — the grid is fully rendered at build time, there’s nothing to wait for. A shimmering skeleton would be actively misleading here, so the placeholder is just a dashed-border card with a quiet “More posts coming soon” label:

1
<div class="card card__blog card__blog--placeholder" aria-hidden="true">
2
  <div class="card__blog--placeholder-inner">
3
    <span class="card__blog--placeholder-label">More posts coming soon</span>
4
  </div>
5
</div>

aria-hidden="true" and pointer-events: none keep it invisible to screen readers and non-interactive, since there’s nothing behind it to click or announce.

Pagination controls

The navigation sits below the grid and only renders when there’s more than one page. Previous and next links use the prevUrl/nextUrl props passed in from the route files. Page number buttons are generated from totalPages, routed through a small pageUrl() helper so the same markup works for both /blog/page/N and a tag page’s paginationBase:

1
function pageUrl(n: number) {
2
  if (paginationBase) {
3
    return n === 1 ? paginationBase : `${paginationBase}/${n}`;
4
  }
5
  return n === 1 ? "/blog" : `/blog/page/${n}`;
6
}

1
{Array.from({ length: totalPages }).map((_, i) => {
2
  const n = i + 1;
3
  return (
4
    <a href={pageUrl(n)} aria-current={n === currentPage ? "page" : undefined}>
5
      {n}
6
    </a>
7
  );
8
})}

The n === 1 branch ensures the first page button always links to /blog (or the tag’s base URL), never /blog/page/1.

Disabled states on Previous/Next use aria-disabled and pointer-events: none rather than swapping <a> for <span>, which keeps the DOM structure consistent across all pages.

What this produces

At build time, Astro generates:

1
dist/blog/index.html        ← page 1
2
dist/blog/page/2/index.html ← page 2 (when posts > 9)
3
dist/blog/page/3/index.html ← page 3 (when posts > 18)

Everything is static HTML. No client-side JavaScript, no API calls, no hydration — the pagination just works as links between pre-rendered pages.

As more posts are published, the grid fills naturally. Once 10 posts exist, page 2 appears automatically at the next build.

Full code listing

1
---
2
import { getCollection } from "astro:content";
3
import { isPublished } from "../../../utils/drafts";
4
import BaseLayout from "../../../layouts/BaseLayout.astro";
5
import PageHero from "../../../components/PageHero.astro";
6
import MailingListCTA from "../../../components/MailingListCTA.astro";
7
import BlogGrid from "../../../components/BlogGrid.astro";
8
import BlogTagCloud from "../../../components/BlogTagCloud.astro";
9

10
export async function getStaticPaths() {
11
  const PAGE_SIZE = 9;
12
  const allPosts = (await getCollection("posts"))
13
    .filter(isPublished)
14
    .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
15
  const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
16
  return Array.from({ length: totalPages - 1 }, (_, i) => ({
17
    params: { page: String(i + 2) },
18
  }));
19
}
20

21
const PAGE_SIZE = 9;
22
const currentPage = Number(Astro.params.page);
23

24
const allPosts = (await getCollection("posts"))
25
  .filter(isPublished)
26
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
27

28
const totalPages = Math.ceil(allPosts.length / PAGE_SIZE);
29
const posts = allPosts.slice(
30
  (currentPage - 1) * PAGE_SIZE,
31
  currentPage * PAGE_SIZE,
32
);
33
const prevUrl = currentPage === 2 ? "/blog" : `/blog/page/${currentPage - 1}`;
34
const nextUrl =
35
  currentPage < totalPages ? `/blog/page/${currentPage + 1}` : null;
36
---
37

38
<BaseLayout pageTitle={`Blog — Page ${currentPage} — Sourcier`}>
39
  <PageHero kicker="Writing" title="Blog" subtitle="..." />
40

41
  <BlogGrid
42
    posts={posts}
43
    currentPage={currentPage}
44
    totalPages={totalPages}
45
    prevUrl={prevUrl}
46
    nextUrl={nextUrl}
47
    sectionLabel="Archive"
48
    sectionTitle={`Posts on page ${currentPage}`}
49
    sectionDescription={`Page ${currentPage} of ${totalPages} from the blog archive.`}
50
  />
51

52
  <BlogTagCloud />
53
  <MailingListCTA />
54
</BaseLayout>

1
---
2
import type { CollectionEntry } from "astro:content";
3
import BlogPost from "./BlogPost.astro";
4
import BlogCardPlaceholder from "./BlogCardPlaceholder.astro";
5
import readingTime from "reading-time";
6

7
interface Props {
8
  posts: CollectionEntry<"posts">[];
9
  currentPage: number;
10
  totalPages: number;
11
  prevUrl: string | null;
12
  nextUrl: string | null;
13
  paginationBase?: string;
14
  sectionLabel?: string;
15
  sectionTitle?: string;
16
  sectionDescription?: string;
17
}
18

19
const { posts, currentPage, totalPages, prevUrl, nextUrl, paginationBase } =
20
  Astro.props;
21

22
const showGhostCards = currentPage === totalPages;
23
const TABLET_COLS = 2;
24
const DESKTOP_COLS = 3;
25
const tabletGhostCount = showGhostCards
26
  ? (TABLET_COLS - (posts.length % TABLET_COLS)) % TABLET_COLS
27
  : 0;
28
const desktopGhostCount = showGhostCards
29
  ? (DESKTOP_COLS - (posts.length % DESKTOP_COLS)) % DESKTOP_COLS
30
  : 0;
31
const sharedGhostCount = Math.min(tabletGhostCount, desktopGhostCount);
32
const tabletOnlyGhostCount = tabletGhostCount - sharedGhostCount;
33
const desktopOnlyGhostCount = desktopGhostCount - sharedGhostCount;
34

35
function pageUrl(n: number) {
36
  if (paginationBase) {
37
    return n === 1 ? paginationBase : `${paginationBase}/${n}`;
38
  }
39
  return n === 1 ? "/blog" : `/blog/page/${n}`;
40
}
41
---
42

43
<section class="section blog-grid-section flow-section">
44
  <div class="container is-max-desktop">
45
    {posts.map((post) => (
46
      <div class="blog-grid__cell">
47
        <BlogPost
48
          title={post.data.title}
49
          url={`/blog/${post.id}`}
50
          cover={post.data.cover}
51
          pubDate={post.data.pubDate}
52
          draft={post.data.draft}
53
          readingTime={readingTime(post.body ?? "").text}
54
        />
55
      </div>
56
    ))}
57
    {Array.from({ length: sharedGhostCount }).map(() => (
58
      <div class="blog-grid__cell blog-grid__ghost-cell blog-grid__ghost-cell--tablet-up">
59
        <BlogCardPlaceholder />
60
      </div>
61
    ))}
62
    {Array.from({ length: tabletOnlyGhostCount }).map(() => (
63
      <div class="blog-grid__cell blog-grid__ghost-cell blog-grid__ghost-cell--tablet-only">
64
        <BlogCardPlaceholder />
65
      </div>
66
    ))}
67
    {Array.from({ length: desktopOnlyGhostCount }).map(() => (
68
      <div class="blog-grid__cell blog-grid__ghost-cell blog-grid__ghost-cell--desktop-only">
69
        <BlogCardPlaceholder />
70
      </div>
71
    ))}
72

73
    {totalPages > 1 && (
74
      <nav class="pagination-nav" aria-label="Blog pagination">
75
        <a
76
          href={prevUrl}
77
          aria-disabled={!prevUrl}
78
          tabindex={!prevUrl ? -1 : 0}
79
        >
80
          &larr; Previous
81
        </a>
82
        <div class="pagination-nav__pages" role="list">
83
          {Array.from({ length: totalPages }).map((_, i) => {
84
            const n = i + 1;
85
            return (
86
              <a
87
                href={pageUrl(n)}
88
                role="listitem"
89
                aria-current={n === currentPage ? "page" : undefined}
90
              >
91
                {n}
92
              </a>
93
            );
94
          })}
95
        </div>
96
        <a href={nextUrl} aria-disabled={!nextUrl} tabindex={!nextUrl ? -1 : 0}>
97
          Next &rarr;
98
        </a>
99
      </nav>
100
    )}
101
  </div>
102
</section>