Manage page visibility

Not every operation in your OpenAPI spec deserves a docs page. Internal endpoints, deprecated routes, partner-only APIs — they belong in the spec (for SDK codegen, for internal tooling) but shouldn't surface to public readers. Mintlify/ReDoc adopted two OpenAPI extensions for this: x-hidden (generate the page but hide from navigation) and x-excluded (don't generate at all). NookDocs supports the hide-from-sidebar side today via MDX frontmatter; the native OpenAPI extensions are on the roadmap.

What ships today

hidden: true on hybrid pages

If an operation is surfaced via a hybrid MDX page (openapi: "METHOD /path" in frontmatter), you can hide it:

---
title: Rotate API key (internal)
openapi: "POST /internal/rotate-api-key"
hidden: true
---

Detailed walkthrough of the key-rotation flow for our CS team...

Effect:

• Page renders at /api-reference/... — URL works for anyone who has it.

• Sidebar drops the entry — no navigation path to the page.

• Search index excludes it — search doesn't surface it.

• Sitemap skips it — search engines don't crawl it.

• llms.txt / llms-full.txt exclude it — LLM crawlers don't ingest it.

• seo.indexing can still override if you want Google to skip even the URL: add noindex: true on the page frontmatter.

See hidden pages and SEO for the mechanics.

Per-group hiding in navigation

A whole nav group can be hidden by setting hidden: true on the group:

{
  "navigation": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Internal APIs",
          "hidden": true,
          "pages": ["docs/api/internal/rotate-key", "docs/api/internal/force-sync"]
        }
      ]
    }
  ]
}

Every page in the group gets hidden — same effect as individual hidden: true on each page.

authGroups (schema-scaffolded, runtime roadmap)

The schema accepts authGroups: ["admin", "devrel"] on groups and pages to gate behind auth. Runtime enforcement isn't wired yet — setting the field today has no effect. When the auth layer ships, these groups will only render for viewers in the matching authGroups. See personalization.

What's on the roadmap

x-hidden — generate but hide

ReDoc / Mintlify convention: add to any operation in your spec, and the generator creates the page but omits it from navigation.

paths:
  /internal/rotate-key:
    post:
      operationId: rotateApiKey
      x-hidden: true
      summary: Rotate API key
      responses:
        '200':
          description: New key returned

Status: not parsed yet. Today the parser includes the operation in navigation regardless. Workaround: back the operation with a hybrid MDX page carrying hidden: true frontmatter.

x-excluded — don't generate at all

Same convention, different semantic: the operation is present in the spec (SDK codegen picks it up) but NookDocs doesn't create a docs page.

paths:
  /internal/purge-cache:
    delete:
      operationId: purgeCache
      x-excluded: true

Status: not parsed yet. Workaround: maintain a secondary reduced spec that omits excluded operations, point api.openapi at the reduced spec, keep the full spec for SDK codegen in a different path. Ugly but works.

x-internal (OpenAPI 3.0 community convention)

Some teams use x-internal: true as a synonym for x-hidden. Parser treats it identically when shipped.

Roadmap details

When these land, the parser will:

1. Walk every path + operation in the spec.

2. If x-excluded: true — skip the operation entirely. Don't emit a page, don't add to sidebar, don't include in sitemap.

3. If x-hidden: true (or x-internal: true) — emit the page, mark it hidden in frontmatter.hidden = true when syncing. Same effect as the manual hidden: true approach.

Tracking: github.com/Codivion/NookDocs/issues?q=x-hidden. Drop a 👍 if you need this.

Practical workarounds today

Workaround 1: hybrid page per internal operation

Create an MDX page for each operation you want hidden, and bind it to the OpenAPI operation via frontmatter:

---
title: Force cache purge
openapi: "DELETE /internal/purge-cache"
hidden: true
---

Operational-only endpoint for the CS team. Reach out in #cs-ops
before hitting this in production.

Effect: the Try-It playground + auto-generated schema still render on the page, but the page never appears in the sidebar, search, sitemap, or llms.txt.

Workaround 2: split into two specs

Ship two OpenAPI files in your repo:

• openapi-public.json — operations you want documented. Point api.openapi at this.

• openapi-full.json — everything including internal operations. Feed this to your SDK codegen.

Only the public spec becomes docs pages. The internal spec stays in the repo for SDK generation without surfacing to readers.

Workaround 3: nav-group exclusion

If you group internal operations under a single tag in your spec, the auto-generator puts them in a single sidebar group (named after the tag). Hide that whole group:

# openapi.json
paths:
  /internal/purge-cache:
    delete:
      tags: [Internal]
      ...
  /internal/rotate-key:
    post:
      tags: [Internal]
      ...

// nookdocs.config.json
{
  "navigation": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Internal",
          "hidden": true
        }
      ]
    }
  ]
}

Every operation tagged Internal hides from the sidebar via the group-level flag.

Deprecated operations (adjacent)

OpenAPI's deprecated: true keyword IS parsed and renders with a strike-through + "Deprecated" badge in the sidebar. Keep the docs visible but signal users to migrate:

paths:
  /v1/old-endpoint:
    get:
      deprecated: true
      summary: Old endpoint (use /v2/new-endpoint)
      x-sunset-date: "2026-12-01"
      ...

Custom x-sunset-date passes through but doesn't render specially — include it in the description if you want readers to see it.

Related

• Schema reference — hidden — the frontmatter field the workarounds use

• Hidden pages — page-level hidden mechanics

• Personalization — viewer-based gating (authGroups, roadmap)

• OpenAPI overview — parser + hybrid page mechanics