Pagefind Exclude: data-pagefind-body vs ignore

2026-08-13

Frontend

Pagefind

/

Astro

/

Search

/

Troubleshooting

Use data-pagefind-body when you want to define the content area that can be searched, and use data-pagefind-ignore when you want to remove a section inside that area. For a template-wide rule that you do not want to express in markup, configure Pagefind’s exclude_selectors option.

The important trap is that data-pagefind-body is an allowlist boundary. Once Pagefind finds that attribute anywhere in a site, pages without it are no longer indexed. A new article layout can therefore make a homepage or landing page disappear from search even though its HTML still looks correct.

Pick the boundary that matches the problem#

Goal	Best tool	What it does
Index only the main content of selected pages	`data-pagefind-body`	Limits indexing to marked regions and makes unmarked pages ineligible once the marker exists anywhere
Remove a sidebar, CTA, or utility block	`data-pagefind-ignore`	Excludes the element and its children from the index inside an indexed region
Remove recurring selectors without changing templates	`exclude_selectors`	Applies CSS selectors during the Pagefind CLI indexing step
Remove a whole page class	Mark only intended pages with `data-pagefind-body`, or limit the CLI glob	Keeps the decision at the page-discovery boundary

The Pagefind indexing documentation describes these as different controls. Do not add data-pagefind-ignore to a page and expect the whole page to vanish; it only affects the marked element.

Index the article body without site chrome#

An Astro or other static-site layout can put the boundary around the content region:

1
<body>
2
  <header>Site navigation</header>
3

4
  <main data-pagefind-body>
5
    <article>
6
      <h1>Pagefind configuration</h1>
7
      <p>This paragraph should be searchable.</p>
8
    </article>
9

10
    <aside data-pagefind-ignore>
11
      Related links and promotional copy should not affect search.
12
    </aside>
13
  </main>
14
</body>

Built-in organizational elements such as nav and footer are already skipped, but custom sidebars, recommendation blocks, and labels may need an explicit boundary. Keep the marker on the same element across the English and Traditional Chinese layouts so both language indexes contain the intended article content. The existing Astro multilingual Pagefind guide covers the separate language-index behavior.

Understand `data-pagefind-ignore` and `all`#

The default form excludes an element and its children from indexed content while still allowing Pagefind to process some metadata and filters inside it:

1
<aside data-pagefind-ignore>
2
  <h2>Related resources</h2>
3
  <p>Not part of the searchable article body.</p>
4
</aside>

Use data-pagefind-ignore="all" when the block should be excluded from all Pagefind processing, including title or metadata detection:

1
<aside data-pagefind-ignore="all">
2
  <h2>This should not provide Pagefind metadata either.</h2>
3
</aside>

The distinction matters when a filtered element contains an image, heading, or custom metadata. Start with the default behavior, then use all only when you have verified that the metadata should be invisible too.

Use `exclude_selectors` for a CLI-level rule#

If the same template classes must be excluded and editing every rendered page is inconvenient, add selectors to pagefind.yml:

1
exclude_selectors:
2
  - ".site-chrome"
3
  - ".recommendation-panel"
4
  - "[data-no-search]"

The Pagefind CLI configuration reference says all children of a matching selector are ignored. A command-line --exclude-selectors value can also contain a comma-separated selector list, but a configuration file is easier to review when the list grows.

Use the markup attributes when the decision belongs to a component. Use CLI selectors when the decision is a build-wide policy. Mixing both is fine, but document which layer owns each exclusion so a future component refactor does not silently reintroduce boilerplate into search results.

Avoid the disappearing-page mistake#

Before adding data-pagefind-body to one article layout, inspect every page type that should remain searchable. Pagefind’s rule is site-wide: if the marker appears anywhere, pages without a marked region are not indexed. Add the marker to the homepage, documentation, or landing-page layouts that should participate, or choose a different discovery boundary.

After changing the markup, verify a production-style build:

1
pnpm build

Then search for a phrase that exists only in an article body, a phrase that exists only in an excluded block, and a page that uses a different layout. This catches both accidental noise and accidental omissions. If the site is multilingual, run the same checks from each language route; the page’s <html lang> value should still select the intended language index.

FAQ#

Does `data-pagefind-ignore` remove a page from search?#

No. It removes the marked element and its children from indexed content. Use the page-body boundary or the CLI’s file-discovery options when the whole page should be excluded.

Why did a page disappear after I added `data-pagefind-body`?#

Once Pagefind finds a body marker anywhere on the site, pages without that marker are not indexed. Add the marker to every page layout that should be searchable or change the indexing strategy.

Should I use `data-pagefind-ignore` or `exclude_selectors`?#

Use the attribute for a local component decision and exclude_selectors for a build-wide CSS-selector policy. Both exclude matching content, but they live at different maintenance boundaries.