[pull] main from facebook:main

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/index.tsx

@@ -31,6 +31,8 @@ import useIsBrowser from '@docusaurus/useIsBrowser';
 import DocSidebarItems from '@theme/DocSidebarItems';
 import type {Props} from '@theme/DocSidebarItem/Category';
 
+import styles from './styles.module.css';
+
 // If we navigate to a category and it becomes active, it should automatically
 // expand itself
 function useAutoExpandActiveCategory({
@@ -126,6 +128,14 @@ function CollapseButton({
   );
 }
 
+function CategoryLinkLabel({label}: {label: string}) {
+  return (
+    <span title={label} className={styles.categoryLinkLabel}>
+      {label}
+    </span>
+  );
+}
+
 export default function DocSidebarItemCategory({
   item,
   onItemClick,
@@ -179,6 +189,29 @@ export default function DocSidebarItemCategory({
     }
   }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
 
+  const handleItemClick: ComponentProps<'a'>['onClick'] = (e) => {
+    onItemClick?.(item);
+    if (collapsible) {
+      if (href) {
+        // When already on the category's page, we collapse it
+        // We don't use "isActive" because it would collapse the
+        // category even when we browse a children element
+        // See https://github.com/facebook/docusaurus/issues/11213
+        if (isCurrentPage) {
+          e.preventDefault();
+          updateCollapsed();
+        } else {
+          // When navigating to a new category, we always expand
+          // see https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182
+          updateCollapsed(false);
+        }
+      } else {
+        e.preventDefault();
+        updateCollapsed();
+      }
+    }
+  };
+
   return (
     <li
       className={clsx(
@@ -195,43 +228,18 @@ export default function DocSidebarItemCategory({
           'menu__list-item-collapsible--active': isCurrentPage,
         })}>
         <Link
-          className={clsx('menu__link', {
+          className={clsx(styles.categoryLink, 'menu__link', {
             'menu__link--sublist': collapsible,
             'menu__link--sublist-caret': !href && collapsible,
             'menu__link--active': isActive,
           })}
-          onClick={
-            collapsible
-              ? (e) => {
-                  onItemClick?.(item);
-                  if (href) {
-                    // When already on the category's page, we collapse it
-                    // We don't use "isActive" because it would collapse the
-                    // category even when we browse a children element
-                    // See https://github.com/facebook/docusaurus/issues/11213
-                    if (isCurrentPage) {
-                      e.preventDefault();
-                      updateCollapsed();
-                    } else {
-                      // When navigating to a new category, we always expand
-                      // see https://github.com/facebook/docusaurus/issues/10854#issuecomment-2609616182
-                      updateCollapsed(false);
-                    }
-                  } else {
-                    e.preventDefault();
-                    updateCollapsed();
-                  }
-                }
-              : () => {
-                  onItemClick?.(item);
-                }
-          }
+          onClick={handleItemClick}
           aria-current={isCurrentPage ? 'page' : undefined}
           role={collapsible && !href ? 'button' : undefined}
           aria-expanded={collapsible && !href ? !collapsed : undefined}
           href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
           {...props}>
-          {label}
+          <CategoryLinkLabel label={label} />
         </Link>
         {href && collapsible && (
           <CollapseButton

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/styles.module.css

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.categoryLink {
+  overflow: hidden;
+}
+
+/*
+TODO merge this logic back in Infima?
+ */
+:global(.menu__link--sublist-caret)::after {
+  margin-left: var(--ifm-menu-link-padding-vertical);
+}
+
+.categoryLinkLabel {
+  flex: 1;
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/index.tsx

@@ -16,6 +16,14 @@ import type {Props} from '@theme/DocSidebarItem/Link';
 
 import styles from './styles.module.css';
 
+function LinkLabel({label}: {label: string}) {
+  return (
+    <span title={label} className={styles.linkLabel}>
+      {label}
+    </span>
+  );
+}
+
 export default function DocSidebarItemLink({
   item,
   onItemClick,
@@ -51,7 +59,7 @@ export default function DocSidebarItemLink({
           onClick: onItemClick ? () => onItemClick(item) : undefined,
         })}
         {...props}>
-        {label}
+        <LinkLabel label={label} />
         {!isInternalLink && <IconExternalLink />}
       </Link>
     </li>

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/styles.module.css

@@ -8,3 +8,11 @@
 .menuExternalLink {
   align-items: center;
 }
+
+.linkLabel {
+  overflow: hidden;
+  display: -webkit-box;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+}

project-words.txt

@@ -136,6 +136,7 @@ lifecycles
 lightningcss
 Linkify
 linkify
+longlonglonglonglonglonglonglonglonglonglonglong
 Lorber
 lorber
 Lorber's

website/_dogfooding/_docs tests/tests/sidebar-display/Category 2 Long Long Long Long Long Long Long Long Long Long Long/doc1.mdx

@@ -0,0 +1 @@
+# Doc 1

website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc1.mdx

@@ -0,0 +1 @@
+# Doc 1

website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc2 long long long long long long long long long long long long.mdx

@@ -0,0 +1 @@
+# Doc 2 long long long long long long long long long long long long

website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc3longlonglonglonglonglonglonglonglonglonglonglong.mdx

@@ -0,0 +1 @@
+# Doc 3 longlonglonglonglonglonglonglonglonglonglonglong

website/_dogfooding/_docs tests/tests/sidebar-display/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Sidebar Display",
+  "link": {
+    "type": "generated-index",
+    "title": "Sidebar Display",
+    "description": "Testing edge cases of how the docs sidebar is displayed"
+  },
+  "position": 1
+}

website/docs/guides/docs/docs-create-doc.mdx

@@ -128,21 +128,23 @@ The ID is used to refer to a document when hand-writing sidebars, or when using
 
 ### Doc URLs {#doc-urls}
 
-By default, a document's URL location is its file path relative to the `docs` folder, with a few exceptions. Namely, if a file is named one the following, the file name won't be included in the URL:
+By default, the document's URL location is derived from the [document `id`](#document-id), which in turn is based on the document's file path.
+
+If a file is named one of the following, the file name won't be included in the URL:
 
 - Named as `index` (case-insensitive): `docs/Guides/index.md`
 - Named as `README` (case-insensitive): `docs/Guides/README.mdx`
 - Same name as parent folder: `docs/Guides/Guides.md`
 
-In all cases, the default slug would only be `/Guides`, without the `/index`, `/README`, or duplicate `/Guides` segment.
+In all cases, the default `slug` would only be `/Guides`, without the `/index`, `/README`, or duplicate `/Guides` segment.
 
 :::note
 
 This convention is exactly the same as [the category index convention](./sidebar/autogenerated.mdx#category-index-convention). However, the `isCategoryIndex` configuration does _not_ affect the document URL.
 
 :::
 
-Use the `slug` front matter to change a document's URL.
+Use the `slug` front matter to provide an explicit document URL and override the default one.
 
 For example, suppose your site structure looks like this:
 
@@ -153,7 +155,7 @@ website # Root directory of your site
         └── hello.md
 ```
 
-By default `hello.md` will be available at `/docs/guide/hello`. You can change its URL location to `/docs/bonjour`:
+By default, `hello.md` will be available at `/docs/guide/hello`. You can change its URL location to `/docs/bonjour`:
 
 ```md
 ---
@@ -174,6 +176,14 @@ It is possible to use:
 
 :::
 
+:::tip
+
+Changing a document's filename or `id`, will change its default URL. To prevent breaking permalinks when renaming files, we recommend setting an explicit `slug` to keep your URLs stable.
+
+:::
+
+#### Making a document available at the root
+
 If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter:
 
 ```md