From ddd5c80b779335fc5e64f1cea1622605cd31625f Mon Sep 17 00:00:00 2001
From: Catherine Deskur <46695336+chdeskur@users.noreply.github.com>
Date: Sat, 11 Jan 2025 15:52:34 -0500
Subject: [PATCH] chore(docs): clarify hidden endpoints (#5583)

Update customize-api-ref.mdx
---
 fern/pages/fern-docs/content/customize-api-ref.mdx | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/fern/pages/fern-docs/content/customize-api-ref.mdx b/fern/pages/fern-docs/content/customize-api-ref.mdx
index 25de94d7066..32c2bb358bf 100644
--- a/fern/pages/fern-docs/content/customize-api-ref.mdx
+++ b/fern/pages/fern-docs/content/customize-api-ref.mdx
@@ -148,9 +148,10 @@ You can hide an endpoint from the API reference by setting `hidden` to `true`. T
 
 <Tabs>
   <Tab title="OpenAPI Specification">
-  ```yaml title="docs.yml" {9-9}
+  ```yaml title="docs.yml" {10}
   navigation: 
     - api: API Reference
+      paginated: true
       layout: 
         - user: 
             - endpoint: POST /user
@@ -161,9 +162,10 @@ You can hide an endpoint from the API reference by setting `hidden` to `true`. T
   ```
   </Tab>
   <Tab title="Fern Definition">
-  ```yaml title="docs.yml" {9-9}
+  ```yaml title="docs.yml" {10}
   navigation: 
     - api: API Reference
+      paginated: true
       layout: 
         - user: 
             - endpoint: user.create
@@ -175,6 +177,10 @@ You can hide an endpoint from the API reference by setting `hidden` to `true`. T
   </Tab>
 </Tabs>
 
+<Tip title="Fully hidden endpoints">
+For best results, API References with hidden endpoints should use the `paginated: true` configuration to avoid discovering endpoints from long-scrolling.
+</Tip>
+
 ### Adding custom sections
 You can add arbitrary folders in the sidebar by adding a `section` to your API Reference layout. A section can comprise entire groups of endpoints, individual endpoints, or even just Markdown pages. Sections can be customized by adding properties like a `icon`, `summary`, `slug` (or `skip-slug`), and `contents`.