feat: Allow to have top level alias for platforms (#13069)

Author: mydea

docs/platforms/javascript/config.yml

@@ -1,4 +1,5 @@
-title: JavaScript
+title: Browser JavaScript
+platformTitle: JavaScript
 caseStyle: camelCase
 supportLevel: production
 sdk: 'sentry.javascript.browser'

src/components/breadcrumbs/index.tsx

@@ -9,20 +9,26 @@ type BreadcrumbsProps = {
 };
 
 export function Breadcrumbs({leafNode}: BreadcrumbsProps) {
-  const nodes: DocNode[] = [];
+  const breadcrumbs: {title: string; to: string}[] = [];
+
   for (let node: DocNode | undefined = leafNode; node; node = node.parent) {
     if (node && !node.missing) {
-      nodes.unshift(node);
+      const to = node.path === '/' ? node.path : `/${node.path}/`;
+      const title = node.frontmatter.platformTitle ?? node.frontmatter.title;
+
+      breadcrumbs.unshift({
+        to,
+        title,
+      });
     }
   }
 
   return (
     <ul className="list-none flex p-0 flex-wrap" style={{margin: 0}}>
-      {nodes.map(n => {
-        const to = n.path === '/' ? n.path : `/${n.path}/`;
+      {breadcrumbs.map(b => {
         return (
-          <li className={styles['breadcrumb-item']} key={n.path}>
-            <SmartLink to={to}>{n.frontmatter.title}</SmartLink>
+          <li className={styles['breadcrumb-item']} key={b.to}>
+            <SmartLink to={b.to}>{b.title}</SmartLink>
           </li>
         );
       })}

src/components/platformFilter/client.tsx

@@ -62,7 +62,7 @@ export function PlatformFilterClient({platforms}: {platforms: Platform[]}) {
       return platformsAndGuides;
     }
     // any of these fields can be used to match the search value
-    const keys = ['title', 'aliases', 'name', 'sdk', 'keywords'];
+    const keys = ['title', 'aliases', 'name', 'sdk', 'keywords', 'platformTitle'];
     const matches_ = matchSorter(platformsAndGuides, filter, {
       keys,
       threshold: rankings.CONTAINS,
@@ -195,7 +195,14 @@ function PlatformWithGuides({
 
   const guides = useMemo(() => {
     const showPlatformInContent = matchKeys.includes(platform.key);
-    return showPlatformInContent ? [platform, ...platform.guides] : platform.guides;
+
+    // This is the case if `platformTitle` is configured for a platform
+    // In this case, we do not need to add the platform to the list of guides
+    const hasGuideWithPlatformKey = platform.guides.some(g => g.key === platform.key);
+
+    return showPlatformInContent && !hasGuideWithPlatformKey
+      ? [platform, ...platform.guides]
+      : platform.guides;
   }, [matchKeys, platform]);
 
   return (

src/components/platformSelector/index.tsx

@@ -92,7 +92,9 @@ export function PlatformSelector({
 
   const router = useRouter();
   const onPlatformChange = (platformKey: string) => {
-    const platform_ = platformsAndGuides.find(platform => platform.key === platformKey);
+    const platform_ = platformsAndGuides.find(
+      platform => platform.key === platformKey.replace('-redirect', '')
+    );
     if (platform_) {
       localStorage.setItem('active-platform', platform_.key);
       router.push(platform_.url);
@@ -277,6 +279,11 @@ function PlatformItem({
       isLastGuide: i === guides.length - 1,
     }));
 
+  // This is the case if `platformTitle` is configured for a platform
+  // In this case, the top-level select item should get the `-redirect` suffix,
+  // as we can't have two items with the same key
+  const hasGuideWithPlatformKey = platform.guides.some(g => g.key === platform.key);
+
   const guides = platform.isExpanded
     ? markLastGuide(platform.guides.length > 0 ? platform.guides : platform.integrations)
     : [];
@@ -288,7 +295,7 @@ function PlatformItem({
         <RadixSelect.Label className="flex">
           <Fragment>
             <RadixSelect.Item
-              value={platform.key}
+              value={hasGuideWithPlatformKey ? `${platform.key}-redirect` : platform.key}
               asChild
               className={styles.item}
               data-platform-with-guides

src/docTree.ts

@@ -259,7 +259,7 @@ function nodeToPlatform(n: DocNode): Platform {
     name: n.slug,
     type: 'platform',
     url: '/' + n.path + '/',
-    title: n.frontmatter.title,
+    title: n.frontmatter.platformTitle ?? n.frontmatter.title,
     caseStyle,
     sdk: n.frontmatter.sdk,
     fallbackPlatform: n.frontmatter.fallbackPlatform,
@@ -369,9 +369,20 @@ function extractGuides(platformNode: DocNode): PlatformGuide[] {
   if (!guidesNode) {
     return [];
   }
-  return guidesNode.children
+
+  // If a `platformTitle` is defined, we add a virtual guide
+  const defaultGuide = platformNode.frontmatter.platformTitle
+    ? {
+        ...nodeToGuide(platformNode.slug, platformNode),
+        key: platformNode.slug,
+      }
+    : undefined;
+
+  const childGuides = guidesNode.children
     .filter(({path}) => !isVersioned(path))
     .map(n => nodeToGuide(platformNode.slug, n));
+
+  return defaultGuide ? [defaultGuide, ...childGuides] : childGuides;
 }
 
 const extractIntegrations = (p: DocNode): PlatformIntegration[] => {

src/types/platform.tsx

@@ -118,6 +118,12 @@ export interface PlatformConfig {
    * Keywords used for search etc.
    */
   keywords?: string[];
+  /**
+   * The title of the platform as it should be displayed in the sidebar.
+   * In most cases, you do not need to define this, as the title is used.
+   * However, in some cases - e.g. JavaScript - the Platform title (JavaScript) is different from the default guide (Browser JavaScript).
+   */
+  platformTitle?: string;
   /**
    * Used to map a platform to a specific SDK as defined by the SDK registry.
    */
@@ -130,7 +136,6 @@ export interface PlatformConfig {
    * Is this a first-party or third-party SDK?
    */
   supportLevel?: PlatformSupportLevel;
-
   /**
    * The human readable name of the platform.
    */