diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/index.tsx
index 22270f21a30f..9a49be27d14e 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/index.tsx
+++ b/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 (
+
+ {label}
+
+ );
+}
+
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 (
{
- 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}
+
{href && collapsible && (
+ {label}
+
+ );
+}
+
export default function DocSidebarItemLink({
item,
onItemClick,
@@ -51,7 +59,7 @@ export default function DocSidebarItemLink({
onClick: onItemClick ? () => onItemClick(item) : undefined,
})}
{...props}>
- {label}
+
{!isInternalLink && }
diff --git a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/styles.module.css b/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/styles.module.css
index 4abcb5676233..a48f210974ac 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/styles.module.css
+++ b/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;
+}
diff --git a/project-words.txt b/project-words.txt
index 36c96b80c8eb..03eeb8db4d4e 100644
--- a/project-words.txt
+++ b/project-words.txt
@@ -136,6 +136,7 @@ lifecycles
lightningcss
Linkify
linkify
+longlonglonglonglonglonglonglonglonglonglonglong
Lorber
lorber
Lorber's
diff --git a/website/_dogfooding/_docs tests/tests/sidebar-display/Category 2 Long Long Long Long Long Long Long Long Long Long Long/doc1.mdx b/website/_dogfooding/_docs tests/tests/sidebar-display/Category 2 Long Long Long Long Long Long Long Long Long Long Long/doc1.mdx
new file mode 100644
index 000000000000..02823ef8d5f8
--- /dev/null
+++ b/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
diff --git a/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc1.mdx b/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc1.mdx
new file mode 100644
index 000000000000..02823ef8d5f8
--- /dev/null
+++ b/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc1.mdx
@@ -0,0 +1 @@
+# Doc 1
diff --git a/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc2 long long long long long long long long long long long long.mdx b/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc2 long long long long long long long long long long long long.mdx
new file mode 100644
index 000000000000..816e33bf628f
--- /dev/null
+++ b/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
diff --git a/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc3longlonglonglonglonglonglonglonglonglonglonglong.mdx b/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc3longlonglonglonglonglonglonglonglonglonglonglong.mdx
new file mode 100644
index 000000000000..0d0eb1de3d50
--- /dev/null
+++ b/website/_dogfooding/_docs tests/tests/sidebar-display/Category1LongLongLongLongLongLongLongLongLongLong/doc3longlonglonglonglonglonglonglonglonglonglonglong.mdx
@@ -0,0 +1 @@
+# Doc 3 longlonglonglonglonglonglonglonglonglonglonglong
diff --git a/website/_dogfooding/_docs tests/tests/sidebar-display/_category_.json b/website/_dogfooding/_docs tests/tests/sidebar-display/_category_.json
new file mode 100644
index 000000000000..8dcbb76c6714
--- /dev/null
+++ b/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
+}
diff --git a/website/docs/guides/docs/docs-create-doc.mdx b/website/docs/guides/docs/docs-create-doc.mdx
index caf8e2ea77b7..b45cf6d33159 100644
--- a/website/docs/guides/docs/docs-create-doc.mdx
+++ b/website/docs/guides/docs/docs-create-doc.mdx
@@ -128,13 +128,15 @@ 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
@@ -142,7 +144,7 @@ This convention is exactly the same as [the category index convention](./sidebar
:::
-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