diff --git a/guides/hidden-page-example.mdx b/guides/hidden-page-example.mdx new file mode 100644 index 000000000..c8941fc23 --- /dev/null +++ b/guides/hidden-page-example.mdx @@ -0,0 +1,53 @@ +--- +title: "Hidden page example" +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 + + + 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**: 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. + +## Examples + +### 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. +``` + +### 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 +``` + +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. + +```` \ No newline at end of file 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.