change structure

Author: mydea

docs/platforms/javascript/config.yml

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

src/components/breadcrumbs/index.tsx

@@ -23,7 +23,7 @@ export function Breadcrumbs({leafNode}: BreadcrumbsProps) {
         return (
           <li className={styles['breadcrumb-item']} key={n.path}>
             <SmartLink to={to}>
-              {n.frontmatter.topLevelAlias ?? n.frontmatter.title}
+              {n.frontmatter.platformTitle ?? n.frontmatter.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', 'topLevelAlias'];
+    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 (
@@ -213,7 +220,7 @@ function PlatformWithGuides({
               format="lg"
               className={`${styles.PlatformIcon} !border-none !shadow-none`}
             />
-            {platform.topLevelAlias ?? platform.title}
+            {platform.title}
           </div>
           <button className={styles.ChevronButton}>
             <TriangleRightIcon

src/components/platformSelector/index.tsx

@@ -279,17 +279,13 @@ function PlatformItem({
       isLastGuide: i === guides.length - 1,
     }));
 
-  const isPlatformWithGuidesAndTopLevelAlias =
-    platform.guides.length > 0 && !!platform.topLevelAlias;
+  // 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
-          ? isPlatformWithGuidesAndTopLevelAlias
-            ? [platform as unknown as PlatformGuide, ...platform.guides]
-            : platform.guides
-          : platform.integrations
-      )
+    ? markLastGuide(platform.guides.length > 0 ? platform.guides : platform.integrations)
     : [];
 
   return (
@@ -299,11 +295,7 @@ function PlatformItem({
         <RadixSelect.Label className="flex">
           <Fragment>
             <RadixSelect.Item
-              value={
-                isPlatformWithGuidesAndTopLevelAlias
-                  ? `${platform.key}-redirect`
-                  : platform.key
-              }
+              value={hasGuideWithPlatformKey ? `${platform.key}-redirect` : platform.key}
               asChild
               className={styles.item}
               data-platform-with-guides
@@ -318,7 +310,7 @@ function PlatformItem({
                       format="sm"
                       className={styles['platform-icon']}
                     />
-                    {platform.topLevelAlias ?? platform.title}
+                    {platform.title}
                   </span>
                 </RadixSelect.ItemText>
               </ComboboxItem>

src/docTree.ts

@@ -253,22 +253,20 @@ function nodeToPlatform(n: DocNode): Platform {
   const caseStyle = platformData?.case_style || n.frontmatter.caseStyle;
   const guides = extractGuides(n);
   const integrations = extractIntegrations(n);
-  const topLevelAlias = n.frontmatter.topLevelAlias;
 
   return {
     key: n.slug,
     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,
     categories: n.frontmatter.categories,
     keywords: n.frontmatter.keywords,
     guides,
     integrations,
-    topLevelAlias,
   };
 }
 
@@ -371,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.
    */
@@ -134,10 +140,6 @@ export interface PlatformConfig {
    * The human readable name of the platform.
    */
   title?: string;
-  /**
-   * Alias for the top level platform name.
-   */
-  topLevelAlias?: string;
 }
 
 /**