Skip to content

Add .pkgdownignore support (#2959)#2971

Open
kyleGrealis wants to merge 2 commits intor-lib:mainfrom
kyleGrealis:issue-2959-pkgdownignore
Open

Add .pkgdownignore support (#2959)#2971
kyleGrealis wants to merge 2 commits intor-lib:mainfrom
kyleGrealis:issue-2959-pkgdownignore

Conversation

@kyleGrealis
Copy link

@kyleGrealis kyleGrealis commented Feb 3, 2026

Summary

This PR adds support for a .pkgdownignore file that allows users to exclude specific markdown files from being rendered to HTML during build_home().

Fixes #2959

Motivation

With the rise of AI coding assistants, developers are increasingly adding files like CLAUDE.md, AGENTS.md, and COPILOT.md to their package roots. These files are developer-facing and shouldn't appear in user documentation or site search results.
Currently, there's no way to exclude arbitrary markdown files from pkgdown builds. The only options are:

  • Move files elsewhere (breaks tool conventions)
  • Delete before CI builds (fragile)
  • Prefix with _ (only works for vignettes)

Solution

A simple .pkgdownignore file that lists filenames to exclude:

# AI assistant configuration
CLAUDE.md
AGENTS.md

# Internal docs
INTERNAL.md
Features
  • Supports comments (#) and blank lines
  • Can be placed in package root, pkgdown/, or _pkgdown/
  • Files from all locations are combined and deduplicated
  • Matches by basename (works for both root and .github/ files)
  • Displays ignored files during build: Ignoring: CLAUDE.md and AGENTS.md

Changes

  • R/build-home-md.R: Added read_pkgdownignore() helper and integrated into package_mds()
  • tests/testthat/test-pkgdownignore.R: 15 tests covering all functionality
  • NEWS.md: Added bullet for this feature

Example

# .pkgdownignore
CLAUDE.md
AGENTS.md

In the build output:

── Building home ───────────────────────────────────────────────────────
Ignoring: CLAUDE.md and AGENTS.md
Reading .github/CODE_OF_CONDUCT.md
Reading .github/CONTRIBUTING.md

Adds support for a .pkgdownignore file that allows users to exclude
specific markdown files from being rendered to HTML during site builds.

The file uses a simple format (one filename per line, # comments supported)
and can be placed in the package root, pkgdown/, or _pkgdown/ directories.
Files from all locations are combined.

Closes r-lib#2959
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature: Allow for file exclusions

1 participant