@docusaurus/plugin-content-docs 0.0.0-4240 → 0.0.0-4241

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/lib/.tsbuildinfo +1 -1
  2. package/lib/categoryGeneratedIndex.d.ts +12 -0
  3. package/lib/categoryGeneratedIndex.js +37 -0
  4. package/lib/cli.js +5 -23
  5. package/lib/docs.d.ts +22 -2
  6. package/lib/docs.js +71 -29
  7. package/lib/index.js +34 -62
  8. package/lib/options.js +2 -0
  9. package/lib/props.js +35 -6
  10. package/lib/routes.d.ts +27 -0
  11. package/lib/routes.js +105 -0
  12. package/lib/sidebars/generator.d.ts +2 -1
  13. package/lib/sidebars/generator.js +55 -13
  14. package/lib/sidebars/index.d.ts +5 -4
  15. package/lib/sidebars/index.js +18 -9
  16. package/lib/sidebars/normalization.d.ts +8 -3
  17. package/lib/sidebars/normalization.js +36 -17
  18. package/lib/sidebars/processor.d.ts +5 -3
  19. package/lib/sidebars/processor.js +33 -18
  20. package/lib/sidebars/types.d.ts +43 -2
  21. package/lib/sidebars/utils.d.ts +18 -6
  22. package/lib/sidebars/utils.js +149 -24
  23. package/lib/sidebars/validation.d.ts +2 -0
  24. package/lib/sidebars/validation.js +44 -8
  25. package/lib/slug.d.ts +4 -3
  26. package/lib/slug.js +26 -14
  27. package/lib/translations.js +51 -7
  28. package/lib/types.d.ts +18 -3
  29. package/package.json +8 -8
  30. package/src/__tests__/__fixtures__/versioned-site/versioned_sidebars/version-1.0.1-sidebars.json +2 -2
  31. package/src/__tests__/__snapshots__/cli.test.ts.snap +48 -106
  32. package/src/__tests__/__snapshots__/index.test.ts.snap +279 -28
  33. package/src/__tests__/__snapshots__/translations.test.ts.snap +45 -0
  34. package/src/__tests__/docs.test.ts +122 -7
  35. package/src/__tests__/index.test.ts +27 -1
  36. package/src/__tests__/options.test.ts +2 -0
  37. package/src/__tests__/slug.test.ts +127 -20
  38. package/src/__tests__/translations.test.ts +7 -0
  39. package/src/categoryGeneratedIndex.ts +57 -0
  40. package/src/cli.ts +5 -35
  41. package/src/docs.ts +103 -45
  42. package/src/index.ts +55 -93
  43. package/src/options.ts +4 -0
  44. package/src/plugin-content-docs.d.ts +71 -8
  45. package/src/props.ts +48 -9
  46. package/src/routes.ts +173 -0
  47. package/src/sidebars/__tests__/__snapshots__/index.test.ts.snap +21 -6
  48. package/src/sidebars/__tests__/generator.test.ts +105 -1
  49. package/src/sidebars/__tests__/index.test.ts +26 -24
  50. package/src/sidebars/__tests__/processor.test.ts +110 -19
  51. package/src/sidebars/__tests__/utils.test.ts +320 -20
  52. package/src/sidebars/__tests__/validation.test.ts +105 -0
  53. package/src/sidebars/generator.ts +82 -19
  54. package/src/sidebars/index.ts +23 -13
  55. package/src/sidebars/normalization.ts +47 -23
  56. package/src/sidebars/processor.ts +57 -27
  57. package/src/sidebars/types.ts +64 -3
  58. package/src/sidebars/utils.ts +217 -42
  59. package/src/sidebars/validation.ts +52 -8
  60. package/src/slug.ts +32 -17
  61. package/src/translations.ts +74 -8
  62. package/src/types.ts +22 -5
@@ -6,7 +6,7 @@
6
6
  * LICENSE file in the root directory of this source tree.
7
7
  */
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
- exports.createSidebarsUtils = exports.collectSidebarsDocIds = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.transformSidebarItems = exports.isCategoriesShorthand = void 0;
9
+ exports.toNavigationLink = exports.toDocNavigationLink = exports.createSidebarsUtils = exports.collectSidebarsNavigations = exports.collectSidebarsDocIds = exports.collectSidebarNavigation = exports.collectSidebarDocIds = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.transformSidebarItems = exports.isCategoriesShorthand = void 0;
10
10
  const lodash_1 = require("lodash");
11
11
  const utils_1 = require("@docusaurus/utils");
12
12
  function isCategoriesShorthand(item) {
@@ -26,13 +26,18 @@ function transformSidebarItems(sidebar, updateFn) {
26
26
  return sidebar.map(transformRecursive);
27
27
  }
28
28
  exports.transformSidebarItems = transformSidebarItems;
29
- function collectSidebarItemsOfType(type, sidebar) {
30
- function collectRecursive(item) {
31
- const currentItemsCollected = item.type === type ? [item] : [];
32
- const childItemsCollected = item.type === 'category' ? item.items.flatMap(collectRecursive) : [];
33
- return [...currentItemsCollected, ...childItemsCollected];
29
+ // Flatten sidebar items into a single flat array (containing categories/docs on the same level)
30
+ // /!\ order matters (useful for next/prev nav), top categories appear before their child elements
31
+ function flattenSidebarItems(items) {
32
+ function flattenRecursive(item) {
33
+ return item.type === 'category'
34
+ ? [item, ...item.items.flatMap(flattenRecursive)]
35
+ : [item];
34
36
  }
35
- return sidebar.flatMap(collectRecursive);
37
+ return items.flatMap(flattenRecursive);
38
+ }
39
+ function collectSidebarItemsOfType(type, sidebar) {
40
+ return flattenSidebarItems(sidebar).filter((item) => item.type === type);
36
41
  }
37
42
  function collectSidebarDocItems(sidebar) {
38
43
  return collectSidebarItemsOfType('doc', sidebar);
@@ -46,12 +51,43 @@ function collectSidebarLinks(sidebar) {
46
51
  return collectSidebarItemsOfType('link', sidebar);
47
52
  }
48
53
  exports.collectSidebarLinks = collectSidebarLinks;
54
+ // /!\ docId order matters for navigation!
55
+ function collectSidebarDocIds(sidebar) {
56
+ return flattenSidebarItems(sidebar).flatMap((item) => {
57
+ var _a;
58
+ if (item.type === 'category') {
59
+ return ((_a = item.link) === null || _a === void 0 ? void 0 : _a.type) === 'doc' ? [item.link.id] : [];
60
+ }
61
+ if (item.type === 'doc') {
62
+ return [item.id];
63
+ }
64
+ return [];
65
+ });
66
+ }
67
+ exports.collectSidebarDocIds = collectSidebarDocIds;
68
+ function collectSidebarNavigation(sidebar) {
69
+ return flattenSidebarItems(sidebar).flatMap((item) => {
70
+ if (item.type === 'category' && item.link) {
71
+ return [item];
72
+ }
73
+ if (item.type === 'doc') {
74
+ return [item];
75
+ }
76
+ return [];
77
+ });
78
+ }
79
+ exports.collectSidebarNavigation = collectSidebarNavigation;
49
80
  function collectSidebarsDocIds(sidebars) {
50
- return (0, lodash_1.mapValues)(sidebars, (sidebar) => collectSidebarDocItems(sidebar).map((docItem) => docItem.id));
81
+ return (0, lodash_1.mapValues)(sidebars, collectSidebarDocIds);
51
82
  }
52
83
  exports.collectSidebarsDocIds = collectSidebarsDocIds;
84
+ function collectSidebarsNavigations(sidebars) {
85
+ return (0, lodash_1.mapValues)(sidebars, collectSidebarNavigation);
86
+ }
87
+ exports.collectSidebarsNavigations = collectSidebarsNavigations;
53
88
  function createSidebarsUtils(sidebars) {
54
89
  const sidebarNameToDocIds = collectSidebarsDocIds(sidebars);
90
+ const sidebarNameToNavigationItems = collectSidebarsNavigations(sidebars);
55
91
  // Reverse mapping
56
92
  const docIdToSidebarName = Object.fromEntries(Object.entries(sidebarNameToDocIds).flatMap(([sidebarName, docIds]) => docIds.map((docId) => [docId, sidebarName])));
57
93
  function getFirstDocIdOfFirstSidebar() {
@@ -61,24 +97,68 @@ function createSidebarsUtils(sidebars) {
61
97
  function getSidebarNameByDocId(docId) {
62
98
  return docIdToSidebarName[docId];
63
99
  }
64
- function getDocNavigation(docId) {
65
- const sidebarName = getSidebarNameByDocId(docId);
100
+ function emptySidebarNavigation() {
101
+ return {
102
+ sidebarName: undefined,
103
+ previous: undefined,
104
+ next: undefined,
105
+ };
106
+ }
107
+ function getDocNavigation(unversionedId, versionedId) {
108
+ // TODO legacy id retro-compatibility!
109
+ let docId = unversionedId;
110
+ let sidebarName = getSidebarNameByDocId(docId);
111
+ if (!sidebarName) {
112
+ docId = versionedId;
113
+ sidebarName = getSidebarNameByDocId(docId);
114
+ }
66
115
  if (sidebarName) {
67
- const docIds = sidebarNameToDocIds[sidebarName];
68
- const currentIndex = docIds.indexOf(docId);
69
- const { previous, next } = (0, utils_1.getElementsAround)(docIds, currentIndex);
70
- return {
71
- sidebarName,
72
- previousId: previous,
73
- nextId: next,
74
- };
116
+ const navigationItems = sidebarNameToNavigationItems[sidebarName];
117
+ const currentItemIndex = navigationItems.findIndex((item) => {
118
+ if (item.type === 'doc') {
119
+ return item.id === docId;
120
+ }
121
+ if (item.type === 'category' && item.link.type === 'doc') {
122
+ return item.link.id === docId;
123
+ }
124
+ return false;
125
+ });
126
+ const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
127
+ return { sidebarName, previous, next };
75
128
  }
76
129
  else {
77
- return {
78
- sidebarName: undefined,
79
- previousId: undefined,
80
- nextId: undefined,
81
- };
130
+ return emptySidebarNavigation();
131
+ }
132
+ }
133
+ function getCategoryGeneratedIndexList() {
134
+ return Object.values(sidebarNameToNavigationItems)
135
+ .flat()
136
+ .flatMap((item) => {
137
+ if (item.type === 'category' && item.link.type === 'generated-index') {
138
+ return [item];
139
+ }
140
+ return [];
141
+ });
142
+ }
143
+ // We identity the category generated index by its permalink (should be unique)
144
+ // More reliable than using object identity
145
+ function getCategoryGeneratedIndexNavigation(categoryGeneratedIndexPermalink) {
146
+ var _a;
147
+ function isCurrentCategoryGeneratedIndexItem(item) {
148
+ var _a;
149
+ return (item.type === 'category' &&
150
+ ((_a = item.link) === null || _a === void 0 ? void 0 : _a.type) === 'generated-index' &&
151
+ item.link.permalink === categoryGeneratedIndexPermalink);
152
+ }
153
+ const sidebarName = (_a = Object.entries(sidebarNameToNavigationItems).find(([, navigationItems]) => navigationItems.find(isCurrentCategoryGeneratedIndexItem))) === null || _a === void 0 ? void 0 : _a[0];
154
+ if (sidebarName) {
155
+ const navigationItems = sidebarNameToNavigationItems[sidebarName];
156
+ const currentItemIndex = navigationItems.findIndex(isCurrentCategoryGeneratedIndexItem);
157
+ const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
158
+ return { sidebarName, previous, next };
159
+ }
160
+ else {
161
+ return emptySidebarNavigation();
82
162
  }
83
163
  }
84
164
  function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
@@ -90,14 +170,59 @@ These sidebar document ids do not exist:
90
170
  - ${invalidSidebarDocIds.sort().join('\n- ')}
91
171
 
92
172
  Available document ids are:
93
- - ${validDocIds.sort().join('\n- ')}`);
173
+ - ${(0, lodash_1.uniq)(validDocIds).sort().join('\n- ')}`);
94
174
  }
95
175
  }
96
176
  return {
177
+ sidebars,
97
178
  getFirstDocIdOfFirstSidebar,
98
179
  getSidebarNameByDocId,
99
180
  getDocNavigation,
181
+ getCategoryGeneratedIndexList,
182
+ getCategoryGeneratedIndexNavigation,
100
183
  checkSidebarsDocIds,
101
184
  };
102
185
  }
103
186
  exports.createSidebarsUtils = createSidebarsUtils;
187
+ function toDocNavigationLink(doc) {
188
+ var _a;
189
+ const { title, permalink, frontMatter: { pagination_label: paginationLabel, sidebar_label: sidebarLabel, }, } = doc;
190
+ return { title: (_a = paginationLabel !== null && paginationLabel !== void 0 ? paginationLabel : sidebarLabel) !== null && _a !== void 0 ? _a : title, permalink };
191
+ }
192
+ exports.toDocNavigationLink = toDocNavigationLink;
193
+ function toNavigationLink(navigationItem, docsById) {
194
+ function getDocById(docId) {
195
+ const doc = docsById[docId];
196
+ if (!doc) {
197
+ throw new Error(`Can't create navigation link: no doc found with id=${docId}`);
198
+ }
199
+ return doc;
200
+ }
201
+ function handleCategory(category) {
202
+ if (category.link.type === 'doc') {
203
+ return toDocNavigationLink(getDocById(category.link.id));
204
+ }
205
+ else if (category.link.type === 'generated-index') {
206
+ return {
207
+ title: category.label,
208
+ permalink: category.link.permalink,
209
+ };
210
+ }
211
+ else {
212
+ throw new Error('unexpected category link type');
213
+ }
214
+ }
215
+ if (!navigationItem) {
216
+ return undefined;
217
+ }
218
+ if (navigationItem.type === 'doc') {
219
+ return toDocNavigationLink(getDocById(navigationItem.id));
220
+ }
221
+ else if (navigationItem.type === 'category') {
222
+ return handleCategory(navigationItem);
223
+ }
224
+ else {
225
+ throw new Error('unexpected navigation item');
226
+ }
227
+ }
228
+ exports.toNavigationLink = toNavigationLink;
@@ -5,4 +5,6 @@
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  */
7
7
  import type { SidebarsConfig } from './types';
8
+ import { CategoryMetadataFile } from './generator';
8
9
  export declare function validateSidebars(sidebars: unknown): asserts sidebars is SidebarsConfig;
10
+ export declare function validateCategoryMetadataFile(unsafeContent: unknown): CategoryMetadataFile;
@@ -6,7 +6,7 @@
6
6
  * LICENSE file in the root directory of this source tree.
7
7
  */
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
- exports.validateSidebars = void 0;
9
+ exports.validateCategoryMetadataFile = exports.validateSidebars = void 0;
10
10
  const utils_validation_1 = require("@docusaurus/utils-validation");
11
11
  const utils_1 = require("./utils");
12
12
  const sidebarItemBaseSchema = utils_validation_1.Joi.object({
@@ -32,6 +32,35 @@ const sidebarItemLinkSchema = sidebarItemBaseSchema.append({
32
32
  .required()
33
33
  .messages({ 'any.unknown': '"label" must be a string' }),
34
34
  });
35
+ const sidebarItemCategoryLinkSchema = utils_validation_1.Joi.object()
36
+ .when('.type', {
37
+ switch: [
38
+ {
39
+ is: 'doc',
40
+ then: utils_validation_1.Joi.object({
41
+ type: 'doc',
42
+ id: utils_validation_1.Joi.string().required(),
43
+ }),
44
+ },
45
+ {
46
+ is: 'generated-index',
47
+ then: utils_validation_1.Joi.object({
48
+ type: 'generated-index',
49
+ slug: utils_validation_1.Joi.string().optional(),
50
+ // permalink: Joi.string().optional(), // No, this one is not in the user config, only in the normalized version
51
+ title: utils_validation_1.Joi.string().optional(),
52
+ description: utils_validation_1.Joi.string().optional(),
53
+ }),
54
+ },
55
+ {
56
+ is: utils_validation_1.Joi.string().required(),
57
+ then: utils_validation_1.Joi.forbidden().messages({
58
+ 'any.unknown': 'Unknown sidebar category link type "{.type}".',
59
+ }),
60
+ },
61
+ ],
62
+ })
63
+ .id('sidebarCategoryLinkSchema');
35
64
  const sidebarItemCategorySchema = sidebarItemBaseSchema.append({
36
65
  type: 'category',
37
66
  label: utils_validation_1.Joi.string()
@@ -41,6 +70,7 @@ const sidebarItemCategorySchema = sidebarItemBaseSchema.append({
41
70
  items: utils_validation_1.Joi.array()
42
71
  .required()
43
72
  .messages({ 'any.unknown': '"items" must be an array' }),
73
+ link: sidebarItemCategoryLinkSchema,
44
74
  collapsed: utils_validation_1.Joi.boolean().messages({
45
75
  'any.unknown': '"collapsed" must be a boolean',
46
76
  }),
@@ -59,13 +89,7 @@ const sidebarItemSchema = utils_validation_1.Joi.object()
59
89
  { is: 'autogenerated', then: sidebarItemAutogeneratedSchema },
60
90
  { is: 'category', then: sidebarItemCategorySchema },
61
91
  {
62
- is: 'subcategory',
63
- then: utils_validation_1.Joi.forbidden().messages({
64
- 'any.unknown': 'Docusaurus v2: "subcategory" has been renamed as "category".',
65
- }),
66
- },
67
- {
68
- is: utils_validation_1.Joi.string().required(),
92
+ is: utils_validation_1.Joi.any().required(),
69
93
  then: utils_validation_1.Joi.forbidden().messages({
70
94
  'any.unknown': 'Unknown sidebar item type "{.type}".',
71
95
  }),
@@ -100,3 +124,15 @@ function validateSidebars(sidebars) {
100
124
  });
101
125
  }
102
126
  exports.validateSidebars = validateSidebars;
127
+ const categoryMetadataFileSchema = utils_validation_1.Joi.object({
128
+ label: utils_validation_1.Joi.string(),
129
+ position: utils_validation_1.Joi.number(),
130
+ collapsed: utils_validation_1.Joi.boolean(),
131
+ collapsible: utils_validation_1.Joi.boolean(),
132
+ className: utils_validation_1.Joi.string(),
133
+ link: sidebarItemCategoryLinkSchema,
134
+ });
135
+ function validateCategoryMetadataFile(unsafeContent) {
136
+ return utils_validation_1.Joi.attempt(unsafeContent, categoryMetadataFileSchema);
137
+ }
138
+ exports.validateCategoryMetadataFile = validateCategoryMetadataFile;
package/lib/slug.d.ts CHANGED
@@ -4,11 +4,12 @@
4
4
  * This source code is licensed under the MIT license found in the
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  */
7
- import type { NumberPrefixParser } from './types';
8
- export default function getSlug({ baseID, frontmatterSlug, dirName, stripDirNumberPrefixes, numberPrefixParser, }: {
7
+ import type { DocMetadataBase, NumberPrefixParser } from './types';
8
+ export default function getSlug({ baseID, frontmatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
9
9
  baseID: string;
10
10
  frontmatterSlug?: string;
11
- dirName: string;
11
+ source: DocMetadataBase['slug'];
12
+ sourceDirName: DocMetadataBase['sourceDirName'];
12
13
  stripDirNumberPrefixes?: boolean;
13
14
  numberPrefixParser?: NumberPrefixParser;
14
15
  }): string;
package/lib/slug.js CHANGED
@@ -8,23 +8,33 @@
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
9
  const utils_1 = require("@docusaurus/utils");
10
10
  const numberPrefix_1 = require("./numberPrefix");
11
- function getSlug({ baseID, frontmatterSlug, dirName, stripDirNumberPrefixes = true, numberPrefixParser = numberPrefix_1.DefaultNumberPrefixParser, }) {
12
- const baseSlug = frontmatterSlug || baseID;
13
- let slug;
14
- if (baseSlug.startsWith('/')) {
15
- slug = baseSlug;
16
- }
17
- else {
11
+ const docs_1 = require("./docs");
12
+ function getSlug({ baseID, frontmatterSlug, source, sourceDirName, stripDirNumberPrefixes = true, numberPrefixParser = numberPrefix_1.DefaultNumberPrefixParser, }) {
13
+ function getDirNameSlug() {
18
14
  const dirNameStripped = stripDirNumberPrefixes
19
- ? (0, numberPrefix_1.stripPathNumberPrefixes)(dirName, numberPrefixParser)
20
- : dirName;
21
- const resolveDirname = dirName === '.'
15
+ ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, numberPrefixParser)
16
+ : sourceDirName;
17
+ const resolveDirname = sourceDirName === '.'
22
18
  ? '/'
23
19
  : (0, utils_1.addLeadingSlash)((0, utils_1.addTrailingSlash)(dirNameStripped));
24
- slug = (0, utils_1.resolvePathname)(baseSlug, resolveDirname);
20
+ return resolveDirname;
21
+ }
22
+ function computeSlug() {
23
+ if (frontmatterSlug === null || frontmatterSlug === void 0 ? void 0 : frontmatterSlug.startsWith('/')) {
24
+ return frontmatterSlug;
25
+ }
26
+ else {
27
+ const dirNameSlug = getDirNameSlug();
28
+ if (!frontmatterSlug && (0, docs_1.isConventionalDocIndex)({ source, sourceDirName })) {
29
+ return dirNameSlug;
30
+ }
31
+ const baseSlug = frontmatterSlug || baseID;
32
+ return (0, utils_1.resolvePathname)(baseSlug, getDirNameSlug());
33
+ }
25
34
  }
26
- if (!(0, utils_1.isValidPathname)(slug)) {
27
- throw new Error(`We couldn't compute a valid slug for document with id "${baseID}" in "${dirName}" directory.
35
+ function ensureValidSlug(slug) {
36
+ if (!(0, utils_1.isValidPathname)(slug)) {
37
+ throw new Error(`We couldn't compute a valid slug for document with id "${baseID}" in "${sourceDirName}" directory.
28
38
  The slug we computed looks invalid: ${slug}.
29
39
  Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
30
40
  By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
@@ -34,7 +44,9 @@ Example =>
34
44
  slug: /my/customDocPath
35
45
  ---
36
46
  `);
47
+ }
48
+ return slug;
37
49
  }
38
- return slug;
50
+ return ensureValidSlug(computeSlug());
39
51
  }
40
52
  exports.default = getSlug;
@@ -75,13 +75,39 @@ function translateDocs(
75
75
  */
76
76
  function getSidebarTranslationFileContent(sidebar, sidebarName) {
77
77
  const categories = (0, utils_1.collectSidebarCategories)(sidebar);
78
- const categoryContent = (0, lodash_1.chain)(categories)
79
- .keyBy((category) => `sidebar.${sidebarName}.category.${category.label}`)
80
- .mapValues((category) => ({
81
- message: category.label,
82
- description: `The label for category ${category.label} in sidebar ${sidebarName}`,
83
- }))
84
- .value();
78
+ const categoryContent = Object.fromEntries(categories.flatMap((category) => {
79
+ const entries = [];
80
+ entries.push([
81
+ `sidebar.${sidebarName}.category.${category.label}`,
82
+ {
83
+ message: category.label,
84
+ description: `The label for category ${category.label} in sidebar ${sidebarName}`,
85
+ },
86
+ ]);
87
+ if (category.link) {
88
+ if (category.link.type === 'generated-index') {
89
+ if (category.link.title) {
90
+ entries.push([
91
+ `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`,
92
+ {
93
+ message: category.link.title,
94
+ description: `The generated-index page title for category ${category.label} in sidebar ${sidebarName}`,
95
+ },
96
+ ]);
97
+ }
98
+ if (category.link.description) {
99
+ entries.push([
100
+ `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`,
101
+ {
102
+ message: category.link.description,
103
+ description: `The generated-index page description for category ${category.label} in sidebar ${sidebarName}`,
104
+ },
105
+ ]);
106
+ }
107
+ }
108
+ }
109
+ return entries;
110
+ }));
85
111
  const links = (0, utils_1.collectSidebarLinks)(sidebar);
86
112
  const linksContent = (0, lodash_1.chain)(links)
87
113
  .keyBy((link) => `sidebar.${sidebarName}.link.${link.label}`)
@@ -93,12 +119,30 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
93
119
  return (0, utils_2.mergeTranslations)([categoryContent, linksContent]);
94
120
  }
95
121
  function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
122
+ function transformSidebarCategoryLink(category) {
123
+ var _a, _b, _c, _d;
124
+ if (!category.link) {
125
+ return undefined;
126
+ }
127
+ if (category.link.type === 'generated-index') {
128
+ const title = (_b = (_a = sidebarsTranslations[`sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : category.link.title;
129
+ const description = (_d = (_c = sidebarsTranslations[`sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`]) === null || _c === void 0 ? void 0 : _c.message) !== null && _d !== void 0 ? _d : category.link.description;
130
+ return {
131
+ ...category.link,
132
+ title,
133
+ description,
134
+ };
135
+ }
136
+ return category.link;
137
+ }
96
138
  return (0, utils_1.transformSidebarItems)(sidebar, (item) => {
97
139
  var _a, _b, _c, _d;
98
140
  if (item.type === 'category') {
141
+ const link = transformSidebarCategoryLink(item);
99
142
  return {
100
143
  ...item,
101
144
  label: (_b = (_a = sidebarsTranslations[`sidebar.${sidebarName}.category.${item.label}`]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : item.label,
145
+ ...(link && { link }),
102
146
  };
103
147
  }
104
148
  if (item.type === 'link') {
package/lib/types.d.ts CHANGED
@@ -5,7 +5,7 @@
5
5
  * LICENSE file in the root directory of this source tree.
6
6
  */
7
7
  import type { RemarkAndRehypePluginOptions } from '@docusaurus/mdx-loader';
8
- import type { Tag, FrontMatterTag } from '@docusaurus/utils';
8
+ import type { Tag, FrontMatterTag, Slugger } from '@docusaurus/utils';
9
9
  import type { BrokenMarkdownLink as IBrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
10
10
  import type { SidebarItemsGeneratorOption, Sidebars } from './sidebars/types';
11
11
  export declare type DocFile = {
@@ -68,6 +68,10 @@ export declare type SidebarOptions = {
68
68
  sidebarCollapsible: boolean;
69
69
  sidebarCollapsed: boolean;
70
70
  };
71
+ export declare type NormalizeSidebarsParams = SidebarOptions & {
72
+ version: VersionMetadata;
73
+ categoryLabelSlugger: Slugger;
74
+ };
71
75
  export declare type PluginOptions = MetadataOptions & PathOptions & VersionsOptions & RemarkAndRehypePluginOptions & SidebarOptions & {
72
76
  id: string;
73
77
  include: string[];
@@ -76,6 +80,7 @@ export declare type PluginOptions = MetadataOptions & PathOptions & VersionsOpti
76
80
  docItemComponent: string;
77
81
  docTagDocListComponent: string;
78
82
  docTagsListComponent: string;
83
+ docCategoryGeneratedIndexComponent: string;
79
84
  admonitions: Record<string, unknown>;
80
85
  disableVersioning: boolean;
81
86
  includeCurrentVersion: boolean;
@@ -109,9 +114,9 @@ export declare type DocFrontMatter = {
109
114
  pagination_prev?: string | null;
110
115
  };
111
116
  export declare type DocMetadataBase = LastUpdateData & {
112
- version: VersionName;
113
- unversionedId: string;
114
117
  id: string;
118
+ unversionedId: string;
119
+ version: VersionName;
115
120
  isDocsHomePage: boolean;
116
121
  title: string;
117
122
  description: string;
@@ -133,6 +138,15 @@ export declare type DocMetadata = DocMetadataBase & {
133
138
  previous?: DocNavLink;
134
139
  next?: DocNavLink;
135
140
  };
141
+ export declare type CategoryGeneratedIndexMetadata = {
142
+ title: string;
143
+ description?: string;
144
+ slug: string;
145
+ permalink: string;
146
+ sidebar: string;
147
+ previous?: DocNavLink;
148
+ next?: DocNavLink;
149
+ };
136
150
  export declare type SourceToPermalink = {
137
151
  [source: string]: string;
138
152
  };
@@ -149,6 +163,7 @@ export declare type LoadedVersion = VersionMetadata & {
149
163
  mainDocId: string;
150
164
  docs: DocMetadata[];
151
165
  sidebars: Sidebars;
166
+ categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
152
167
  };
153
168
  export declare type LoadedContent = {
154
169
  loadedVersions: LoadedVersion[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@docusaurus/plugin-content-docs",
3
- "version": "0.0.0-4240",
3
+ "version": "0.0.0-4241",
4
4
  "description": "Docs plugin for Docusaurus.",
5
5
  "main": "lib/index.js",
6
6
  "types": "src/plugin-content-docs.d.ts",
@@ -18,7 +18,7 @@
18
18
  },
19
19
  "license": "MIT",
20
20
  "devDependencies": {
21
- "@docusaurus/module-type-aliases": "0.0.0-4240",
21
+ "@docusaurus/module-type-aliases": "0.0.0-4241",
22
22
  "@types/js-yaml": "^4.0.0",
23
23
  "@types/picomatch": "^2.2.1",
24
24
  "commander": "^5.1.0",
@@ -26,11 +26,11 @@
26
26
  "utility-types": "^3.10.0"
27
27
  },
28
28
  "dependencies": {
29
- "@docusaurus/core": "0.0.0-4240",
30
- "@docusaurus/mdx-loader": "0.0.0-4240",
31
- "@docusaurus/types": "0.0.0-4240",
32
- "@docusaurus/utils": "0.0.0-4240",
33
- "@docusaurus/utils-validation": "0.0.0-4240",
29
+ "@docusaurus/core": "0.0.0-4241",
30
+ "@docusaurus/mdx-loader": "0.0.0-4241",
31
+ "@docusaurus/types": "0.0.0-4241",
32
+ "@docusaurus/utils": "0.0.0-4241",
33
+ "@docusaurus/utils-validation": "0.0.0-4241",
34
34
  "chalk": "^4.1.2",
35
35
  "combine-promises": "^1.1.0",
36
36
  "escape-string-regexp": "^4.0.0",
@@ -53,5 +53,5 @@
53
53
  "engines": {
54
54
  "node": ">=14"
55
55
  },
56
- "gitHead": "7402103577fe6c4f5f45cc3bc98a397c54e6a34e"
56
+ "gitHead": "c9609b8c3e97c86812a67a377c7f0ebdca8b07f0"
57
57
  }
@@ -1,7 +1,7 @@
1
1
  {
2
- "version-1.0.1/docs": {
2
+ "VersionedSideBarNameDoesNotMatter/docs": {
3
3
  "Test": [
4
- "version-1.0.1/foo/bar"
4
+ "foo/bar"
5
5
  ],
6
6
  "Guides": [
7
7
  "version-1.0.1/hello"