Skip to content
Reed Docs

Fix "is not referenced by any navigation entry"

Every page in the content directory must be listed in navigation. reed check reports each one that is not.

Symptom

Section titled “Symptom”

reed check fails with content-page-not-in-navigation. For a file content/orphan-probe.mdx that is not listed anywhere in navigation:

txt
  ✗ [content-page-not-in-navigation] content file "orphan-probe.mdx" is not referenced by any navigation entry; a page must be listed in docs.json navigation to be built
check failed.

The path is relative to your content directory. reed build runs the same check first, so it stops with the same line before it builds anything. Every unlisted file gets its own line, so one run shows all of them.

If the file also fails to parse, you get both errors for it: unparseable-mdx (or a frontmatter error) and content-page-not-in-navigation. Fixing one does not clear the other.

What you saw before this diagnostic existed

Section titled “What you saw before this diagnostic existed”

Older Reed releases did not check for this. reed check passed, and reed build failed partway through rendering pages:

txt
├─ /orphan-probe/index.html [ERROR] AstroUserError: Failed to find the topic for the `orphan-probe` page.
[ERROR] [build] Caught error rendering /orphan-probe: AstroUserError: Failed to find the topic for the `orphan-probe` page.
[AstroUserError] Failed to find the topic for the `orphan-probe` page.
  Hint:
    Either include this page in the sidebar configuration of the desired topic using the `items` property, associate an unlisted page with a topic using the `topic` frontmatter property or the `topics` option, or exclude this page from any topic using the `exclude` option.

The id in backticks is the page id, derived from the file’s path under the content directory: slugified, with a nested index collapsed into its directory, and replaced outright by a frontmatter slug when the page sets one. content/guides/old-draft.mdx fails as guides/old-draft. See Navigation for the full rule. If you still see this build error, upgrade Reed: reed check now catches it.

Cause

Section titled “Cause”

Every .mdx or .md file in your content directory becomes a page, and every page must belong to a group in navigation. A file that exists on disk but is listed nowhere has no place in the sidebar, and the site generator Reed builds on refuses to render it.

The one exception is a file whose own name starts with _, such as guides/_shared.mdx. It is never loaded as a page, so it needs no navigation entry and reed check does not report it. A _-prefixed directory does not count: _partials/shared.mdx is loaded as a page and is reported like any other file.

Reed has no hidden-pages feature. The old build error’s hint mentions a topic frontmatter property and topics / exclude options from the underlying sidebar plugin. Reed does not expose any of them. Reed’s frontmatter is title and description, plus slug (see Navigation) and type: changelog, none of which hides a page, and docs.json has no setting for unlisted pages.

Common ways to end up here: a draft page saved into content/, a page removed from navigation but not deleted, a file renamed on disk while navigation still lists the old id, or a stray copy such as quickstart-old.mdx.

Fix

Section titled “Fix”

Find the file in the message, then choose one for each:

List the page in a group

Section titled “List the page in a group”

If the page should be published, add its id to the pages of a group in docs.json:

json
{
  "label": "Guides",
  "pages": ["guides/linking", "guides/media", "orphan-probe"]
}

Remove it from the content directory

Section titled “Remove it from the content directory”

If the page is a draft or a leftover, delete it or move it out of the content directory entirely — anywhere Reed does not read:

sh
mkdir -p drafts
git mv content/orphan-probe.mdx drafts/orphan-probe.mdx

Verify

Section titled “Verify”
sh
reed check

The content-page-not-in-navigation line is gone. If you listed the page, it appears in the sidebar after the next reed build. If you removed it, no page for that id is written.

Section titled “Related”