feat: top level versioning for platforms and guides

Author: chargome

app/[[...path]]/page.tsx

@@ -16,10 +16,14 @@ import {
   nodeForPath,
 } from 'sentry-docs/docTree';
 import {isDeveloperDocs} from 'sentry-docs/isDeveloperDocs';
-import {getDevDocsFrontMatter, getDocsFrontMatter, getFileBySlug} from 'sentry-docs/mdx';
+import {
+  getDevDocsFrontMatter,
+  getDocsFrontMatter,
+  getFileBySlug,
+  getVersionsFromDoc,
+} from 'sentry-docs/mdx';
 import {mdxComponents} from 'sentry-docs/mdxComponents';
 import {setServerContext} from 'sentry-docs/serverContext';
-import {VERSION_INDICATOR} from 'sentry-docs/versioning';
 
 export async function generateStaticParams() {
   const docs = await (isDeveloperDocs ? getDevDocsFrontMatter() : getDocsFrontMatter());
@@ -90,6 +94,7 @@ export default async function Page({params}: {params: {path?: string[]}}) {
   }
 
   const pageNode = nodeForPath(rootNode, params.path);
+
   if (!pageNode) {
     // eslint-disable-next-line no-console
     console.warn('no page node', params.path);
@@ -111,19 +116,8 @@ export default async function Page({params}: {params: {path?: string[]}}) {
   const {mdxSource, frontMatter} = doc;
 
   // collect versioned files
-  const versions = (await getDocsFrontMatter())
-    .filter(({slug}) => {
-      return (
-        slug.includes(VERSION_INDICATOR) &&
-        pageNode.path
-          .split(VERSION_INDICATOR)[0]
-          .includes(slug.split(VERSION_INDICATOR)[0])
-      );
-    })
-    .map(({slug}) => {
-      const segments = slug.split(VERSION_INDICATOR);
-      return segments[segments.length - 1];
-    });
+  const allFm = await getDocsFrontMatter();
+  const versions = getVersionsFromDoc(allFm, pageNode.path);
 
   // pass frontmatter tree into sidebar, rendered page + fm into middle, headers into toc.
   return (

src/components/docPage/index.tsx

@@ -4,6 +4,7 @@ import {getCurrentGuide, getCurrentPlatform, nodeForPath} from 'sentry-docs/docT
 import {serverContext} from 'sentry-docs/serverContext';
 import {FrontMatter} from 'sentry-docs/types';
 import {isTruthy} from 'sentry-docs/utils';
+import {getUnversionedPath} from 'sentry-docs/versioning';
 
 import './type.scss';
 
@@ -43,14 +44,18 @@ export function DocPage({
 
   const searchPlatforms = [currentPlatform?.name, currentGuide?.name].filter(isTruthy);
 
-  const leafNode = nodeForPath(rootNode, path);
+  const unversionedPath = getUnversionedPath(path, false);
+
+  const leafNode = nodeForPath(rootNode, unversionedPath);
 
   return (
     <div className="tw-app">
       <Header pathname={pathname} searchPlatforms={searchPlatforms} />
 
       <section className="px-0 flex relative">
-        {sidebar ?? <Sidebar path={path} versions={frontMatter.versions} />}
+        {sidebar ?? (
+          <Sidebar path={unversionedPath.split('/')} versions={frontMatter.versions} />
+        )}
         <main className="main-content flex w-full mt-[var(--header-height)] flex-1 mx-auto">
           <div
             className={[

src/components/dynamicNav.tsx

@@ -2,7 +2,7 @@ import {Fragment} from 'react';
 
 import {serverContext} from 'sentry-docs/serverContext';
 import {sortPages} from 'sentry-docs/utils';
-import {VERSION_INDICATOR} from 'sentry-docs/versioning';
+import {getUnversionedPath, VERSION_INDICATOR} from 'sentry-docs/versioning';
 
 import {NavChevron} from './sidebar/navChevron';
 import {SidebarLink} from './sidebarLink';
@@ -31,11 +31,11 @@ export interface EntityTree extends Entity<EntityTree> {}
 export const toTree = (nodeList: Node[]): EntityTree[] => {
   const result: EntityTree[] = [];
   const level = {result};
-
   nodeList
     .sort((a, b) => a.path.localeCompare(b.path))
     .forEach(node => {
       let curPath = '';
+
       // hide versioned pages in sidebar
       if (!node.path.includes(VERSION_INDICATOR)) {
         node.path.split('/').reduce((r, name: string) => {
@@ -54,8 +54,7 @@ export const toTree = (nodeList: Node[]): EntityTree[] => {
       }
     });
 
-  result.length; // result[0] is undefined without this. wat
-  return result[0].children;
+  return result.length > 0 ? result[0].children : [];
 };
 
 export const renderChildren = (
@@ -168,7 +167,7 @@ export function DynamicNav({
     parentNode && !noHeadingLink ? (
       <SmartLink
         to={`/${root}/`}
-        className={`${headerClassName} ${path.join('/') === root ? 'active' : ''} justify-between`}
+        className={`${headerClassName} ${getUnversionedPath(path, false) === root ? 'active' : ''} justify-between`}
         activeClassName="active"
         data-sidebar-link
       >

src/components/platformCategorySection.tsx

@@ -19,8 +19,7 @@ const isSupported = (
     return false;
   }
 
-  // @ts-ignore
-  const categories = Object.values(platformOrGuide.categories) as string[];
+  const categories = (platformOrGuide.categories || []) as string[];
 
   if (supported.length && !supported.some(v => categories.includes(v))) {
     return false;

src/components/versionSelector/index.tsx

@@ -62,7 +62,7 @@ export function VersionSelector({versions, sdk}: {sdk: string; versions: string[
       pathVersion !== storedSelection &&
       versions.includes(storedSelection)
     ) {
-      router.replace(getVersionedPathname(storedSelection));
+      // router.replace(getVersionedPathname(storedSelection));
     }
   }, [
     getCurrentVersion,

src/docTree.ts

@@ -8,6 +8,7 @@ import {
   PlatformGuide,
   PlatformIntegration,
 } from './types';
+import {isVersioned, VERSION_INDICATOR} from './versioning';
 
 export interface DocNode {
   children: DocNode[];
@@ -133,6 +134,7 @@ function frontmatterToTree(frontmatter: FrontMatter[]): DocNode {
 export function nodeForPath(node: DocNode, path: string | string[]): DocNode | undefined {
   const stringPath = typeof path === 'string' ? path : path.join('/');
   const parts = slugWithoutIndex(stringPath);
+
   for (let i = 0; i < parts.length; i++) {
     const maybeChild = node.children.find(child => child.slug === parts[i]);
     if (maybeChild) {
@@ -196,15 +198,15 @@ export function getCurrentPlatform(
   if (path.length < 2 || path[0] !== 'platforms') {
     return undefined;
   }
-  return getPlatform(rootNode, path[1]);
+  return getPlatform(rootNode, path[1].split(VERSION_INDICATOR)[0]);
 }
 
 export function getCurrentGuide(
   rootNode: DocNode,
   path: string[]
 ): PlatformGuide | undefined {
   if (path.length >= 4 && path[2] === 'guides') {
-    return getGuide(rootNode, path[1], path[3]);
+    return getGuide(rootNode, path[1], path[3].split(VERSION_INDICATOR)[0]);
   }
 
   return undefined;
@@ -243,15 +245,19 @@ export function extractPlatforms(rootNode: DocNode): Platform[] {
     return [];
   }
 
-  return platformsNode.children.map(nodeToPlatform);
+  return platformsNode.children
+    .filter(({path}) => !isVersioned(path))
+    .map(nodeToPlatform);
 }
 
 function extractGuides(platformNode: DocNode): PlatformGuide[] {
   const guidesNode = nodeForPath(platformNode, 'guides');
   if (!guidesNode) {
     return [];
   }
-  return guidesNode.children.map(n => nodeToGuide(platformNode.slug, n));
+  return guidesNode.children
+    .filter(({path}) => !isVersioned(path))
+    .map(n => nodeToGuide(platformNode.slug, n));
 }
 
 const extractIntegrations = (p: DocNode): PlatformIntegration[] => {

src/mdx.spec.ts

@@ -1,6 +1,18 @@
 import {describe, expect, test} from 'vitest';
 
-import {getVersionedIndexPath} from './mdx';
+import {getVersionedIndexPath, getVersionsFromDoc} from './mdx';
+import {FrontMatter} from './types';
+
+const mockFm: FrontMatter[] = [
+  {
+    title: 'js',
+    slug: 'platforms/javascript',
+  },
+  {
+    title: 'go',
+    slug: 'platforms/go',
+  },
+];
 
 describe('mdx', () => {
   describe('getVersionedIndexPath', () => {
@@ -27,5 +39,56 @@ describe('mdx', () => {
         '/does/not/exist.mdx'
       );
     });
+    test('return versioned path for root level common file', () => {
+      expect(
+        getVersionedIndexPath('/', 'docs/platforms/javascript__v7/common', '.mdx')
+      ).toBe('/docs/platforms/javascript/common/index__v7.mdx');
+    });
+  });
+
+  describe('getVersionsFromDoc', () => {
+    test('should return no versions from unversioned docs', () => {
+      const fm: FrontMatter[] = [...mockFm];
+      const versions = getVersionsFromDoc(fm, '/platforms/javascript');
+      expect(versions).toHaveLength(0);
+    });
+
+    test('should return one version from versioned docs', () => {
+      const fm: FrontMatter[] = [
+        ...mockFm,
+        {title: 'js', slug: 'platforms/javascript__v2'},
+        {title: 'go', slug: 'platforms/go__v2'},
+      ];
+      const versions = getVersionsFromDoc(fm, '/platforms/javascript');
+      expect(versions).toHaveLength(1);
+      expect(versions).toContain('2');
+    });
+
+    test('should return several versions from versioned docs', () => {
+      const fm: FrontMatter[] = [
+        ...mockFm,
+        {title: 'js', slug: 'platforms/javascript__v2'},
+        {title: 'js', slug: 'platforms/javascript__v1.23'},
+        {title: 'js', slug: 'platforms/javascript__v1.23.1'},
+        {title: 'go', slug: 'platforms/go__v2'},
+      ];
+      const versions = getVersionsFromDoc(fm, '/platforms/javascript');
+      expect(versions).toHaveLength(3);
+      expect(versions).toContain('1.23');
+      expect(versions).toContain('1.23.1');
+      expect(versions).toContain('2');
+    });
+
+    test('should not contain duplicates', () => {
+      const fm: FrontMatter[] = [
+        ...mockFm,
+        {title: 'js', slug: 'platforms/javascript__v2'},
+        {title: 'js', slug: 'platforms/javascript/guides/nextjs'},
+        {title: 'js', slug: 'platforms/javascript/guides/nextjs__v2'},
+      ];
+      const versions = getVersionsFromDoc(fm, 'platforms/javascript/guides/nextjs');
+      expect(versions).toHaveLength(1);
+      expect(versions).toContain('2');
+    });
   });
 });

src/mdx.ts

@@ -70,6 +70,26 @@ export function getDocsFrontMatter(): Promise<FrontMatter[]> {
   return getDocsFrontMatterCache;
 }
 
+/**
+ * collect all available versions for a given document path
+ */
+export const getVersionsFromDoc = (frontMatter: FrontMatter[], docPath: string) => {
+  const versions = frontMatter
+    .filter(({slug}) => {
+      return (
+        slug.includes(VERSION_INDICATOR) &&
+        docPath.split(VERSION_INDICATOR)[0].includes(slug.split(VERSION_INDICATOR)[0])
+      );
+    })
+    .map(({slug}) => {
+      const segments = slug.split(VERSION_INDICATOR);
+      return segments[segments.length - 1];
+    });
+
+  // remove duplicates
+  return [...new Set(versions)];
+};
+
 async function getDocsFrontMatterUncached(): Promise<FrontMatter[]> {
   const frontMatter = getAllFilesFrontMatter();
 
@@ -256,8 +276,14 @@ export const getVersionedIndexPath = (
   let versionedSlug = 'does/not/exist.mdx';
   const segments = slug.split(VERSION_INDICATOR);
   if (segments.length === 2) {
-    versionedSlug = `${segments[0]}/index${VERSION_INDICATOR}${segments[1]}${fileExtension}`;
+    if (segments[1].includes('common')) {
+      const segmentWithoutCommon = segments[1].split('/common')[0];
+      versionedSlug = `${segments[0]}/common/index${VERSION_INDICATOR}${segmentWithoutCommon}${fileExtension}`;
+    } else {
+      versionedSlug = `${segments[0]}/index${VERSION_INDICATOR}${segments[1]}${fileExtension}`;
+    }
   }
+
   return path.join(pathRoot, versionedSlug);
 };
 
@@ -293,6 +319,7 @@ export async function getFileBySlug(slug: string) {
       commonFilePath = path.join(commonPath, slugParts.slice(5).join('/'));
     } else if (slugParts.length >= 3 && slugParts[1] === 'platforms') {
       commonFilePath = path.join(commonPath, slugParts.slice(3).join('/'));
+      versionedMdxIndexPath = getVersionedIndexPath(root, commonFilePath, '.mdx');
     }
     if (commonFilePath && fs.existsSync(commonPath)) {
       mdxPath = path.join(root, `${commonFilePath}.mdx`);

src/versioning.spec.ts

@@ -8,5 +8,7 @@ describe('versioning', () => {
     expect(getUnversionedPath('/some/path')).toBe('/some/path/');
     expect(getUnversionedPath('/some/path__v2')).toBe('/some/path/');
     expect(getUnversionedPath('/some/path__v2/')).toBe('/some/path/');
+    expect(getUnversionedPath(['some', 'path__v2'])).toBe('some/path/');
+    expect(getUnversionedPath(['some', 'path__v2'], false)).toBe('some/path');
   });
 });

src/versioning.ts

@@ -2,7 +2,13 @@ export const VERSION_INDICATOR = '__v';
 
 export const getLocalStorageVersionKey = (platform: string) => `version:${platform}`;
 
-export const getUnversionedPath = (path: string) => {
-  const unversioned = path.split(VERSION_INDICATOR)[0];
-  return unversioned[unversioned.length - 1] === '/' ? unversioned : `${unversioned}/`;
+export const getUnversionedPath = (path: string | string[], trailingSlash = true) => {
+  const joined = Array.isArray(path) ? path.join('/') : path;
+  const unversioned = joined.split(VERSION_INDICATOR)[0];
+  if (trailingSlash) {
+    return unversioned[unversioned.length - 1] === '/' ? unversioned : `${unversioned}/`;
+  }
+  return unversioned;
 };
+
+export const isVersioned = (path: string) => path.includes(VERSION_INDICATOR);