3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-06-20 19:47:52 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(v2): allow non sidebar category to be first item of sidebar (#2032)

Browse source 
* feat(v2): allow non sidebar category to be first item of sidebar

* better error messages

* edit the react component

* Update website/docs/sidebar.md

* nits

* add @babel/plugin-transform-runtime
This commit is contained in:
Endi 2019-11-24 11:08:19 +07:00 • committed by Yangshun Tay
parent c533adc4aa
commit 9862a6821a
20 changed files with 849 additions and 671 deletions
Download patch file Download diff file Expand all files Collapse all files

111
packages/docusaurus-plugin-content-docs/src/sidebars.ts
View file

@ -8,11 +8,13 @@
import fs from 'fs-extra';
import importFresh from 'import-fresh';
import {
SidebarItemCategory,
Sidebar,
SidebarRaw,
SidebarItem,
SidebarItemCategoryRaw,
SidebarItemRaw,
SidebarItemLink,
SidebarItemDoc,
} from './types';
/**
@ -32,54 +34,71 @@ function assertItem(item: Object, keys: string[]): void {
}
}
function assertIsCategory(item: any): asserts item is SidebarItemCategoryRaw {
assertItem(item, ['items', 'label']);
if (typeof item.label !== 'string') {
throw new Error(
`Error loading ${JSON.stringify(item)}. "label" must be a string.`,
);
}
if (!Array.isArray(item.items)) {
throw new Error(
`Error loading ${JSON.stringify(item)}. "items" must be an array.`,
);
}
}
function assertIsDoc(item: any): asserts item is SidebarItemDoc {
assertItem(item, ['id']);
if (typeof item.id !== 'string') {
throw new Error(
`Error loading ${JSON.stringify(item)}. "id" must be a string.`,
);
}
}
function assertIsLink(item: any): asserts item is SidebarItemLink {
assertItem(item, ['href', 'label']);
if (typeof item.href !== 'string') {
throw new Error(
`Error loading ${JSON.stringify(item)}. "href" must be a string.`,
);
}
if (typeof item.label !== 'string') {
throw new Error(
`Error loading ${JSON.stringify(item)}. "label" must be a string.`,
);
}
}
/**
* Normalizes recursively category and all its children. Ensures, that at the end
* Normalizes recursively item and all its children. Ensures, that at the end
* each item will be an object with the corresponding type
*/
function normalizeCategory(
category: SidebarItemCategoryRaw,
level = 0,
): SidebarItemCategory {
if (level === 0 && category.type !== 'category') {
throw new Error(
`Error loading ${JSON.stringify(
category,
)}. First level item of a sidebar must be a category`,
);
function normalizeItem(item: SidebarItemRaw): SidebarItem {
if (typeof item === 'string') {
return {
type: 'doc',
id: item,
};
}
assertItem(category, ['items', 'label']);
if (!Array.isArray(category.items)) {
throw new Error(
`Error loading "${category.label}" category. Category items must be array.`,
);
if (!item.type) {
throw new Error(`Unknown sidebar item "${JSON.stringify(item)}".`);
}
switch (item.type) {
case 'category':
assertIsCategory(item);
return {...item, items: item.items.map(normalizeItem)};
case 'link':
assertIsLink(item);
return item;
case 'ref':
case 'doc':
assertIsDoc(item);
return item;
default:
throw new Error(`Unknown sidebar item type: ${item.type}`);
}
const items: SidebarItem[] = category.items.map(item => {
if (typeof item === 'string') {
return {
type: 'doc',
id: item,
};
}
switch (item.type) {
case 'category':
return normalizeCategory(item as SidebarItemCategoryRaw, level + 1);
case 'link':
assertItem(item, ['href', 'label']);
break;
case 'ref':
case 'doc':
assertItem(item, ['id']);
break;
default:
throw new Error(`Unknown sidebar item type: ${item.type}`);
}
return item as SidebarItem;
});
return {...category, items};
}
/**
@ -88,7 +107,7 @@ function normalizeCategory(
function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
return Object.entries(sidebars).reduce(
(acc: Sidebar, [sidebarId, sidebar]) => {
let normalizedSidebar: SidebarItemCategoryRaw[];
let normalizedSidebar: SidebarItemRaw[];
if (!Array.isArray(sidebar)) {
// convert sidebar to a more generic structure
@ -101,7 +120,7 @@ function normalizeSidebar(sidebars: SidebarRaw): Sidebar {
normalizedSidebar = sidebar;
}
acc[sidebarId] = normalizedSidebar.map(item => normalizeCategory(item));
acc[sidebarId] = normalizedSidebar.map(normalizeItem);
return acc;
},