Standardizing naming of workspaces in docs

.env

@@ -1,3 +1,5 @@
-NEXT_PUBLIC_CLOUDSMITH_API_URL="https://api.cloudsmith.io/v2"
+NEXT_PUBLIC_CLOUDSMITH_API_URL="https://api.cloudsmith.io"
+NEXT_PUBLIC_CLOUDSMITH_DOCS_URL="https://github.com/cloudsmith-io/cloudsmith-docs"
+NEXT_PUBLIC_CLOUDSMITH_DOCS_BRANCH="main"
 CLOUDSMITH_API_V1_URL="https://api.cloudsmith.io/swagger/?format=openapi"
 CLOUDSMITH_API_V2_URL="https://api.cloudsmith.io/v2/openapi/?format=json"

README.md

@@ -13,6 +13,7 @@ Then refer to the following guides on how to manage the content of the website:
 - [Writing markdown](./docs/markdown.md)
 - [Using snippets](./docs/snippets.md)
 - [Editing menus](./docs/menus.md)
+- [OopenAPI Schemas](./docs/openapi.md)
 
 ## Getting started
 

docs/markdown.md

@@ -69,7 +69,7 @@ In the Guides section, you can use a special `GuideLink` component to show a sol
 ```mdx
 import { GuideLink } from '@/components';
 
-<GuideLink href="/getting-started/api-bindings">Click me</GuideLink>
+<GuideLink href="/api/api-bindings">Click me</GuideLink>
 ```
 
 ## Dividers

docs/openapi.md

@@ -0,0 +1,8 @@
+# OpenAPI Schemas
+
+The `/api` pages are automatically generated based on two OpenAPI files in `src/content/schemas` holding the `v1` and `v2` API paths.
+
+There are two special features:
+
+- If a path has `"experimental"` as a tag, it will be listed with a big noted saying that this API endpoint is in early access.
+- If a path has a `sandboxLink` property with a fully qualified URL, the page will show a API Sandbox link to that URL.

src/app/(api)/Sidebar.tsx

@@ -1,12 +1,12 @@
 import { getMenuItem } from '@/lib/menu/util';
 import { Sidenav } from '@/components';
-import { parseSchema, toMenuItems, toOperations } from '@/lib/swagger/parse';
+import { parseSchemas, toMenuItems, toOperations } from '@/lib/swagger/parse';
 
 export const Sidebar = async () => {
   const menuData = getMenuItem('api');
 
-  const schema = await parseSchema();
-  const operations = toOperations(schema);
+  const schemas = await parseSchemas();
+  const operations = toOperations(schemas);
   const menuItems = toMenuItems(operations);
 
   const allItems = [];

src/app/(api)/api/[...slug]/page.module.css

@@ -10,6 +10,38 @@
   grid-template-columns: minmax(100px, min-content) minmax(150px, auto) 1fr;
 }
 
+.sectionHeading {
+  color: var(--brand-color-grey-7);
+  margin-bottom: var(--space-s);
+}
+
 .fullWidth {
   grid-column: 1 / -1;
 }
+
+.description {
+  display: block;
+
+  .sandboxLink {
+    color: var(--color-text-secondary);
+    display: flex;
+    align-items: center;
+    gap: var(--space-3xs);
+    width: fit-content;
+
+    &:hover {
+      color: var(--brand-color-blue-7);
+    }
+  }
+}
+
+.experimentalTag {
+  margin-bottom: var(--space-s);
+}
+
+@media (--tablet-up) {
+  .description {
+    display: flex;
+    justify-content: space-between;
+  }
+}

src/app/(api)/api/[...slug]/page.tsx

@@ -1,11 +1,15 @@
-import { ApiRequest, ApiResponses, TimeAgo, Heading, Paragraph } from '@/components';
+import { ApiRequest, ApiResponses, TimeAgo, Heading, Paragraph, Tag, Note } from '@/components';
 import { loadMdxInfo } from '@/lib/markdown/util';
-import { parseSchema, toOperations } from '@/lib/swagger/parse';
+import { parseSchemas, toOperations } from '@/lib/swagger/parse';
 import { toRouteSegments, toSlug } from '@/lib/util';
 import { notFound } from 'next/navigation';
 import type { Metadata } from 'next';
 import { withMdxMetadata, withDefaultMetadata, getLastUpdated } from '@/lib/metadata/util';
+import { getMenuItem, getActiveAncestors } from '@/lib/menu/util';
 import WithQuicknav from '@/components/WithQuickNav';
+import { Icon } from '@/icons';
+import { Link } from '@/components';
+import { cx } from 'class-variance-authority';
 
 import styles from './page.module.css';
 
@@ -27,8 +31,8 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
   }
 
   // For Swagger operations, use the operation details
-  const schema = await parseSchema();
-  const operations = toOperations(schema);
+  const schemas = await parseSchemas();
+  const operations = toOperations(schemas);
   const operation = operations.find((op) => op.slug === qualifiedSlug);
 
   if (operation) {
@@ -55,8 +59,8 @@ export const generateStaticParams = async () => {
     .map((info) => ({ slug: info.segments }));
 
   // Generate swagger slugs
-  const schema = await parseSchema();
-  const operations = toOperations(schema);
+  const schemas = await parseSchemas();
+  const operations = toOperations(schemas);
   const operationSlugs = operations.map((op) => ({ slug: toRouteSegments(op.slug) }));
 
   return mdxSlugs.concat(operationSlugs);
@@ -70,29 +74,65 @@ const Page = async ({ params }: PageProps) => {
   const content = await loadMdxInfo('api');
   const mdxInfo = content.find((info) => info.slug === qualifiedSlug);
 
+  const pathname = `${qualifiedSlug}`;
+  const menuData = getMenuItem('api');
+  const ancestors = getActiveAncestors(pathname, [menuData]);
+  const parentTitle = ancestors.length > 1 ? ancestors[ancestors.length - 2].title : null;
+
   if (mdxInfo) {
-    const mdxModule = await import(`@/content/${mdxInfo.file}`);
-    const { default: Post } = mdxModule;
-    const lastUpdated = getLastUpdated(mdxModule);
+    const { default: Post } = await import(`@/content/${mdxInfo.file}`);
+    const lastUpdated = await getLastUpdated(mdxInfo);
 
     return (
       <WithQuicknav>
+        {parentTitle ? (
+          <h2 data-quick-nav-ignore className={cx(styles.sectionHeading, 'monoXSUppercase')}>
+            {parentTitle}
+          </h2>
+        ) : null}
         <Post />
         {lastUpdated ? <TimeAgo date={lastUpdated} /> : null}
       </WithQuicknav>
     );
   }
 
   // Otherwise render as an operation
-  const schema = await parseSchema();
-  const operations = toOperations(schema);
+  const schemas = await parseSchemas();
+  const operations = toOperations(schemas);
   const operation = operations.find((op) => op.slug === qualifiedSlug);
 
   if (operation) {
+    const operationParentTitle =
+      parentTitle ||
+      (operation.menuSegments.length > 1 ? operation.menuSegments[operation.menuSegments.length - 2] : null);
+
     return (
       <div className={styles.root}>
+        {operationParentTitle ? (
+          <h2 data-quick-nav-ignore className={cx(styles.sectionHeading, 'monoXSUppercase')}>
+            {operationParentTitle}
+          </h2>
+        ) : null}
+        {operation.experimental ? (
+          <Tag variant="lightyellow" className={styles.experimentalTag}>
+            Early access
+          </Tag>
+        ) : null}
         <Heading size="h1">{operation.title}</Heading>
-        {operation.description ? <Paragraph>{operation.description}</Paragraph> : null}
+        <div className={styles.description}>
+          {operation.description && <Paragraph>{operation.description}</Paragraph>}
+          {operation.sandboxLink && (
+            <Link href={operation.sandboxLink} className={cx(styles.sandboxLink, 'bodyS')} target="_blank">
+              <span>Open API Sandbox</span>
+              <Icon name="external" title="Open API Sandbox" />
+            </Link>
+          )}
+        </div>
+        {operation.experimental ? (
+          <Note variant="warning" noHeadline>
+            This endpoint is in early access, and may not be available to you. Contact us to request access
+          </Note>
+        ) : null}
 
         <div className={styles.gridRoot}>
           <Heading size="h2" className={styles.fullWidth}>

src/app/(api)/api/page.tsx

@@ -35,9 +35,8 @@ const Page = async () => {
   const mdxInfo = content.find((info) => info.slug === '');
 
   if (mdxInfo) {
-    const mdxModule = await import(`@/content/${mdxInfo.file}`);
-    const { default: Post } = mdxModule;
-    const lastUpdated = getLastUpdated(mdxModule);
+    const { default: Post } = await import(`@/content/${mdxInfo.file}`);
+    const lastUpdated = await getLastUpdated(mdxInfo);
 
     return (
       <WithQuicknav>

src/app/(documentation)/[...slug]/page.module.css

@@ -0,0 +1,4 @@
+.sectionHeading {
+  color: var(--brand-color-grey-7);
+  margin-bottom: var(--space-s);
+}

src/app/(documentation)/[...slug]/page.tsx

@@ -4,7 +4,11 @@ import { notFound } from 'next/navigation';
 import type { Metadata } from 'next';
 import { withMdxMetadata, withDefaultMetadata, getLastUpdated } from '@/lib/metadata/util';
 import { TimeAgo } from '@/components';
+import { getMenuItem, getActiveAncestors } from '@/lib/menu/util';
 import WithQuicknav from '@/components/WithQuickNav';
+import { cx } from 'class-variance-authority';
+
+import styles from './page.module.css';
 
 export const dynamicParams = false;
 
@@ -40,12 +44,26 @@ const Page = async ({ params }: PageProps) => {
   const mdxInfo = content.find((info) => info.slug === qualifiedSlug);
 
   if (mdxInfo) {
-    const mdxModule = await import(`@/content/${mdxInfo.file}`);
-    const { default: Post } = mdxModule;
-    const lastUpdated = getLastUpdated(mdxModule);
+    const { parentTitle: mdxParentTitle, default: Post } = await import(`@/content/${mdxInfo.file}`);
+    const repoPath = `src/content/${mdxInfo.file}`;
+    const lastUpdated = await getLastUpdated(mdxInfo);
+
+    // 2. Original logic: Get parentTitle from the menu system.
+    const pathname = `/${qualifiedSlug}`;
+    const menuData = getMenuItem('documentation');
+    const ancestors = getActiveAncestors(pathname, [menuData]);
+    const menuParentTitle = ancestors.length > 1 ? ancestors[ancestors.length - 2].title : null;
+
+    // 3. Prioritize the title from the MDX file, then fall back to the menu.
+    const parentTitle = mdxParentTitle ?? menuParentTitle;
 
     return (
-      <WithQuicknav>
+      <WithQuicknav showPageInfo path={repoPath} lastUpdated={lastUpdated}>
+        {parentTitle ? (
+          <h2 data-quick-nav-ignore className={cx(styles.sectionHeading, 'monoXSUppercase')}>
+            {parentTitle}
+          </h2>
+        ) : null}
         <Post />
         {lastUpdated ? <TimeAgo date={lastUpdated} /> : null}
       </WithQuicknav>