Skip to content

Commit 86a7527

Browse files
ptgottptgott
authored
Respect sidebar_label when ordering the sidebar (#225)
The `sidebar_label` frontmatter field specifies the name to give a docs page on the auto-generated sidebar. Our custom sidebar ordering logic does not take `sidebar_label` into account when ordering sidebar items automatically by title. This change uses the `sidebar_label` value as the page's title if this frontmatter field is available. This way, sidebar labels continue to be sorted alphabetically unless the user overrides them with `sidebar_position` or the title includes "Introduction" or "Get Started". This change also renames `frontmatter` to `frontMatter` in the `docPage` type to match the data structure passed by Docusaurus.
1 parent 7d46394 commit 86a7527

File tree

2 files changed

+173
-20
lines changed

2 files changed

+173
-20
lines changed

‎server/sidebar-order.test.ts

Lines changed: 169 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ function getDocPageForId(id: string): docPage {
1515
return {
1616
title: title,
1717
id: id,
18-
frontmatter: {
18+
frontMatter: {
1919
title: title,
2020
description: "Provides information on Teleport functionality",
2121
},
@@ -510,7 +510,7 @@ describe("orderSidebarItems", () => {
510510
"page-a": {
511511
title: "Page A",
512512
id: "page-a",
513-
frontmatter: {
513+
frontMatter: {
514514
title: "Page A",
515515
description: "Page A",
516516
},
@@ -520,7 +520,7 @@ describe("orderSidebarItems", () => {
520520
"page-b": {
521521
title: "Page B",
522522
id: "page-b",
523-
frontmatter: {
523+
frontMatter: {
524524
title: "Page B",
525525
description: "Page B",
526526
},
@@ -530,7 +530,7 @@ describe("orderSidebarItems", () => {
530530
"page-c": {
531531
title: "Page C",
532532
id: "page-c",
533-
frontmatter: {
533+
frontMatter: {
534534
title: "Page C",
535535
description: "Page C",
536536
},
@@ -540,7 +540,7 @@ describe("orderSidebarItems", () => {
540540
"page-d": {
541541
title: "Introduction",
542542
id: "page-d",
543-
frontmatter: {
543+
frontMatter: {
544544
title: "Introduction",
545545
description: "Introduction",
546546
},
@@ -550,7 +550,7 @@ describe("orderSidebarItems", () => {
550550
"page-e": {
551551
title: "Page E",
552552
id: "page-e",
553-
frontmatter: {
553+
frontMatter: {
554554
title: "Page E",
555555
description: "Page E",
556556
sidebar_position: 2,
@@ -562,7 +562,7 @@ describe("orderSidebarItems", () => {
562562
"page-f": {
563563
title: "Getting Started",
564564
id: "page-f",
565-
frontmatter: {
565+
frontMatter: {
566566
title: "Getting Started",
567567
description: "Getting Started",
568568
},
@@ -572,7 +572,7 @@ describe("orderSidebarItems", () => {
572572
"page-g": {
573573
title: "Introduction",
574574
id: "page-g",
575-
frontmatter: {
575+
frontMatter: {
576576
title: "Introduction",
577577
description: "Introduction",
578578
},
@@ -760,12 +760,162 @@ describe("orderSidebarItems", () => {
760760
});
761761
});
762762

763+
describe("sidebar label", () => {
764+
const idToDocPage = {
765+
"page-a": {
766+
title: "Page A",
767+
id: "page-a",
768+
frontMatter: {
769+
title: "Page A",
770+
sidebar_label: "Page Z",
771+
description: "Page A",
772+
},
773+
source: "@site/docs/page-a.mdx",
774+
sourceDirName: "",
775+
},
776+
"page-b": {
777+
title: "Page B",
778+
id: "page-b",
779+
frontMatter: {
780+
title: "Page B",
781+
sidebar_label: "Page W",
782+
description: "Page B",
783+
},
784+
source: "@site/docs/page-b.mdx",
785+
sourceDirName: "",
786+
},
787+
"page-c": {
788+
title: "Page C",
789+
id: "page-c",
790+
frontMatter: {
791+
title: "Page C",
792+
sidebar_label: "Page X",
793+
description: "Page C",
794+
},
795+
source: "@site/docs/page-c.mdx",
796+
sourceDirName: "",
797+
},
798+
"page-d": {
799+
title: "Page D",
800+
id: "page-d",
801+
frontMatter: {
802+
title: "Page D",
803+
description: "Page D",
804+
},
805+
source: "@site/docs/page-d.mdx",
806+
sourceDirName: "",
807+
},
808+
};
809+
810+
interface testCase {
811+
description: string;
812+
input: Array<NormalizedSidebarItem>;
813+
expected: Array<NormalizedSidebarItem>;
814+
}
815+
816+
const testCases: Array<testCase> = [
817+
{
818+
description: "all pages use sidebar_label",
819+
input: [
820+
{
821+
type: "category",
822+
label: "My Docs Category",
823+
items: [
824+
{
825+
type: "doc",
826+
id: "page-a",
827+
},
828+
{
829+
type: "doc",
830+
id: "page-b",
831+
},
832+
{
833+
type: "doc",
834+
id: "page-c",
835+
},
836+
],
837+
},
838+
],
839+
expected: [
840+
{
841+
type: "category",
842+
label: "My Docs Category",
843+
items: [
844+
{
845+
type: "doc",
846+
id: "page-b",
847+
},
848+
{
849+
type: "doc",
850+
id: "page-c",
851+
},
852+
{
853+
type: "doc",
854+
id: "page-a",
855+
},
856+
],
857+
},
858+
],
859+
},
860+
{
861+
description: "one page uses title",
862+
input: [
863+
{
864+
type: "category",
865+
label: "My Docs Category",
866+
items: [
867+
{
868+
type: "doc",
869+
id: "page-d",
870+
},
871+
{
872+
type: "doc",
873+
id: "page-b",
874+
},
875+
{
876+
type: "doc",
877+
id: "page-c",
878+
},
879+
],
880+
},
881+
],
882+
expected: [
883+
{
884+
type: "category",
885+
label: "My Docs Category",
886+
items: [
887+
{
888+
type: "doc",
889+
id: "page-d",
890+
},
891+
{
892+
type: "doc",
893+
id: "page-b",
894+
},
895+
{
896+
type: "doc",
897+
id: "page-c",
898+
},
899+
],
900+
},
901+
],
902+
},
903+
];
904+
905+
test.each(testCases)("$description", (c) => {
906+
const actual = orderSidebarItems(c.input, (id: string): docPage => {
907+
return idToDocPage[id];
908+
});
909+
expect(actual).toEqual(c.expected);
910+
});
911+
});
912+
763913
describe("ordering category index pages", () => {
764914
const idToDocPage = {
765915
"section-a/section-a": {
766916
title: "Section A",
767917
id: "section-a/section-a",
768-
frontmatter: {
918+
frontMatter: {
769919
title: "Section A",
770920
description: "Section A",
771921
},
@@ -775,7 +925,7 @@ describe("orderSidebarItems", () => {
775925
"section-a/page-a": {
776926
title: "Section A Page A",
777927
id: "section-a/page-a",
778-
frontmatter: {
928+
frontMatter: {
779929
title: "Section A Page A",
780930
description: "Page A",
781931
},
@@ -785,7 +935,7 @@ describe("orderSidebarItems", () => {
785935
"section-a/page-b": {
786936
title: "Section A Page B",
787937
id: "section-a/page-b",
788-
frontmatter: {
938+
frontMatter: {
789939
title: "Section A Page B",
790940
description: "Page B",
791941
},
@@ -795,7 +945,7 @@ describe("orderSidebarItems", () => {
795945
"section-b/section-b": {
796946
title: "Section B",
797947
id: "section-b/section-b",
798-
frontmatter: {
948+
frontMatter: {
799949
title: "Section B",
800950
description: "Section B",
801951
},
@@ -806,7 +956,7 @@ describe("orderSidebarItems", () => {
806956
"section-b/page-a": {
807957
title: "Section B Page A",
808958
id: "section-b/page-a",
809-
frontmatter: {
959+
frontMatter: {
810960
title: "Section B Page A",
811961
description: "Page A",
812962
},
@@ -817,7 +967,7 @@ describe("orderSidebarItems", () => {
817967
"section-b/page-b": {
818968
title: "Section B Page B",
819969
id: "section-b/page-b",
820-
frontmatter: {
970+
frontMatter: {
821971
title: "Section B Page B",
822972
description: "Page B",
823973
},
@@ -827,7 +977,7 @@ describe("orderSidebarItems", () => {
827977
intro: {
828978
title: "Introduction",
829979
id: "intro",
830-
frontmatter: {
980+
frontMatter: {
831981
title: "Introduction",
832982
description: "Introduction",
833983
},
@@ -936,7 +1086,7 @@ describe("orderSidebarItems", () => {
9361086
"page-a": {
9371087
title: "Page A",
9381088
id: "page-a",
939-
frontmatter: {
1089+
frontMatter: {
9401090
title: "Page A",
9411091
description: "Page A",
9421092
},
@@ -947,7 +1097,7 @@ describe("orderSidebarItems", () => {
9471097
"page-b": {
9481098
title: "Page B",
9491099
id: "page-b",
950-
frontmatter: {
1100+
frontMatter: {
9511101
title: "Page B",
9521102
description: "Page B",
9531103
},
@@ -988,7 +1138,7 @@ describe("orderSidebarItems", () => {
9881138
"page-a": {
9891139
title: "Page A",
9901140
id: "page-a",
991-
frontmatter: {
1141+
frontMatter: {
9921142
title: "Page A",
9931143
description: "Page A",
9941144
},
@@ -999,7 +1149,7 @@ describe("orderSidebarItems", () => {
9991149
"page-b": {
10001150
title: "Page B",
10011151
id: "page-b",
1002-
frontmatter: {
1152+
frontMatter: {
10031153
title: "Page B",
10041154
description: "Page B",
10051155
},

‎server/sidebar-order.ts

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import type {
77
export interface docPage {
88
title: string;
99
id: string;
10-
frontmatter: {
10+
frontMatter: {
1111
[index: string]: any;
1212
};
1313
source: string;
@@ -40,6 +40,9 @@ const getOrderAttributes = (
4040
title = page.title;
4141
sidebarPosition = page.sidebarPosition;
4242
id = page.id;
43+
if (page.frontMatter && page.frontMatter.sidebar_label) {
44+
title = page.frontMatter.sidebar_label;
45+
}
4346
break;
4447
case "category":
4548
const cat = item as NormalizedSidebarItemCategory;

0 commit comments

Comments
 (0)