From b13ee5a91c69f75c3e323fbc9980f8ca4bba04a0 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 23 Jun 2025 11:31:33 -0700 Subject: [PATCH 1/6] add hidden page --- guides/hidden-page-example.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 guides/hidden-page-example.mdx diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx new file mode 100644 index 000000000..d7558d2aa --- /dev/null +++ b/guides/hidden-page-example.mdx @@ -0,0 +1,9 @@ +--- +title: "Hidden page example" +description: "This is a hidden page" +icon: "eye-off" +--- + +This page is hidden! It is not included in the `docs.json` navigation so you can only access it by its URL. + +See [Hidden pages](/guides/hidden-pages) for more information. From a8f797db98a530bb4afc65f87921f12921f5cfeb Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 23 Jun 2025 11:42:19 -0700 Subject: [PATCH 2/6] add link to example hidden page --- guides/hidden-pages.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/guides/hidden-pages.mdx b/guides/hidden-pages.mdx index dc7f02dad..a03592202 100644 --- a/guides/hidden-pages.mdx +++ b/guides/hidden-pages.mdx @@ -18,6 +18,8 @@ A page is hidden if it is not included in your `docs.json` navigation. To hide a Hidden pages use the same URL structure as regular pages based on their file path. For example, `guides/hidden-page.mdx` would be accessible at `docs.yoursite.com/guides/hidden-page`. +See an [example of a hidden page](/guides/hidden-page-example). + Some navigation elements like sidebars, dropdowns, and tabs may appear empty or shift layout on hidden pages. From dc418a206a9259ebebcffc2b0019ec47962bf2cf Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 23 Jun 2025 11:42:27 -0700 Subject: [PATCH 3/6] make example page more informative --- guides/hidden-page-example.mdx | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx index d7558d2aa..0c9fc3cdd 100644 --- a/guides/hidden-page-example.mdx +++ b/guides/hidden-page-example.mdx @@ -1,9 +1,34 @@ --- title: "Hidden page example" -description: "This is a hidden page" +description: "Common use cases for hidden pages" icon: "eye-off" --- This page is hidden! It is not included in the `docs.json` navigation so you can only access it by its URL. See [Hidden pages](/guides/hidden-pages) for more information. + +## Common use cases for hidden pages + + + All hidden pages are public, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [authentication](/authentication-personalization/authentication-setup). + + +- **Beta documentation**: Information that can be public, but should not be discoverable through the navigation. +- **Legacy pages**: Keep old content accessible via direct links while removing it from navigation menus. +- **Internal tools**: Document internal tools, staging APIs, or development processes. +- **Context for AI tools**: Provide context for AI tools. Hidden pages must be indexed to be accessible to AI tools. + +## Example: Internal API endpoint + +```bash +POST /api/internal/reset-cache +Authorization: Bearer internal-token-xyz +``` + +This endpoint clears the application cache and is only available in development environments. + + + This is an internal endpoint and should never be used in production. + + From efb978607546c7a7b52d2dad62f1b3c85cdd2978 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 23 Jun 2025 11:48:07 -0700 Subject: [PATCH 4/6] add example to hidden page --- guides/hidden-page-example.mdx | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx index 0c9fc3cdd..f0aa9e9b1 100644 --- a/guides/hidden-page-example.mdx +++ b/guides/hidden-page-example.mdx @@ -11,16 +11,33 @@ See [Hidden pages](/guides/hidden-pages) for more information. ## Common use cases for hidden pages - All hidden pages are public, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [authentication](/authentication-personalization/authentication-setup). + By default, hidden pages are publicly accessible, but not discoverable through the navigation. If you want to restrict access to a hidden page, you must configure [authentication](/authentication-personalization/authentication-setup). - **Beta documentation**: Information that can be public, but should not be discoverable through the navigation. +- **Context for AI tools**: Provide context for AI tools. Hidden pages must be indexed to be accessible to AI tools. - **Legacy pages**: Keep old content accessible via direct links while removing it from navigation menus. - **Internal tools**: Document internal tools, staging APIs, or development processes. -- **Context for AI tools**: Provide context for AI tools. Hidden pages must be indexed to be accessible to AI tools. + +## Example: AI context + +```mdx wrap +--- +title: "Context for API version" +description: "This page is context for AI tools responding to questions about API versions" +--- + +When a user asks about API versions, always recommend that they use the latest version of the API. Never generate responses for versions older than 1.0.4. +``` ## Example: Internal API endpoint +````mdx wrap +--- +title: "Internal API endpoint" +description: "This page is a hidden page that documents an internal API endpoint" +--- + ```bash POST /api/internal/reset-cache Authorization: Bearer internal-token-xyz @@ -31,4 +48,4 @@ This endpoint clears the application cache and is only available in development This is an internal endpoint and should never be used in production. - +```` \ No newline at end of file From 2cbffac451fc7fcc94b48c4d4aecef6acce12f56 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 23 Jun 2025 11:49:00 -0700 Subject: [PATCH 5/6] formatting --- guides/hidden-page-example.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx index f0aa9e9b1..ddc8bb0c1 100644 --- a/guides/hidden-page-example.mdx +++ b/guides/hidden-page-example.mdx @@ -19,7 +19,9 @@ See [Hidden pages](/guides/hidden-pages) for more information. - **Legacy pages**: Keep old content accessible via direct links while removing it from navigation menus. - **Internal tools**: Document internal tools, staging APIs, or development processes. -## Example: AI context +## Examples + +### AI context ```mdx wrap --- @@ -30,7 +32,7 @@ description: "This page is context for AI tools responding to questions about AP When a user asks about API versions, always recommend that they use the latest version of the API. Never generate responses for versions older than 1.0.4. ``` -## Example: Internal API endpoint +### Internal API endpoint ````mdx wrap --- From ee5c6658b20ebf158f64a76905c4a026947bf614 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 23 Jun 2025 12:07:43 -0700 Subject: [PATCH 6/6] copyedit --- guides/hidden-page-example.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx index ddc8bb0c1..c8941fc23 100644 --- a/guides/hidden-page-example.mdx +++ b/guides/hidden-page-example.mdx @@ -15,7 +15,7 @@ See [Hidden pages](/guides/hidden-pages) for more information. - **Beta documentation**: Information that can be public, but should not be discoverable through the navigation. -- **Context for AI tools**: Provide context for AI tools. Hidden pages must be indexed to be accessible to AI tools. +- **Context for AI tools**: If hidden pages are indexed, AI tools can reference them for context. Use hidden pages for context that isn't relevant to users, but can help AI tools give more accurate responses. - **Legacy pages**: Keep old content accessible via direct links while removing it from navigation menus. - **Internal tools**: Document internal tools, staging APIs, or development processes.