mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-28 16:37:07 +02:00
feat(content-docs): expose isCategoryIndex matcher to customize conventions (#6451)
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
This commit is contained in:
parent
76a8d5f38a
commit
24a895fbc5
16 changed files with 408 additions and 93 deletions
|
@ -194,6 +194,102 @@ Naming your introductory document `README.md` makes it show up when browsing the
|
|||
|
||||
:::
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Customizing category index matching</summary>
|
||||
|
||||
It is possible to opt out any of the category index conventions, or define even more conventions. You can inject your own `isCategoryIndex` matcher through the [`sidebarItemsGenerator`](#customize-the-sidebar-items-generator) callback. For example, you can also pick `intro` as another file name eligible for automatically becoming the category index.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
async sidebarItemsGenerator({
|
||||
...args,
|
||||
isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
|
||||
defaultSidebarItemsGenerator,
|
||||
}) {
|
||||
return defaultSidebarItemsGenerator({
|
||||
...args,
|
||||
// highlight-start
|
||||
isCategoryIndex(doc) {
|
||||
return (
|
||||
// Also pick intro.md in addition to the default ones
|
||||
doc.fileName.toLowerCase() === 'intro' ||
|
||||
defaultCategoryIndexMatcher(doc)
|
||||
);
|
||||
},
|
||||
// highlight-end
|
||||
});
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
Or choose to not have any category index convention.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
async sidebarItemsGenerator({
|
||||
...args,
|
||||
isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
|
||||
defaultSidebarItemsGenerator,
|
||||
}) {
|
||||
return defaultSidebarItemsGenerator({
|
||||
...args,
|
||||
// highlight-start
|
||||
isCategoryIndex() {
|
||||
// No doc will be automatically picked as category index
|
||||
return false;
|
||||
},
|
||||
// highlight-end
|
||||
});
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
The `isCategoryIndex` matcher will be provided with three fields:
|
||||
|
||||
- `fileName`, the file's name without extension and with casing preserved
|
||||
- `directories`, the list of directory names _from the lowest level to the highest level_, relative to the docs root directory
|
||||
- `extension`, the file's extension, with a leading dot.
|
||||
|
||||
For example, for a doc file at `guides/sidebar/autogenerated.md`, the props the matcher receives are
|
||||
|
||||
```js
|
||||
const props = {
|
||||
fileName: 'autogenerated',
|
||||
directories: ['sidebar', 'guides'],
|
||||
extension: '.md',
|
||||
};
|
||||
```
|
||||
|
||||
The default implementation is:
|
||||
|
||||
```js
|
||||
function isCategoryIndex({fileName, directories}) {
|
||||
const eligibleDocIndexNames = [
|
||||
'index',
|
||||
'readme',
|
||||
directories[0].toLowerCase(),
|
||||
];
|
||||
return eligibleDocIndexNames.includes(fileName.toLowerCase());
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
|
||||
|
||||
For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names).
|
||||
|
@ -317,6 +413,7 @@ module.exports = {
|
|||
item,
|
||||
version,
|
||||
docs,
|
||||
isCategoryIndex,
|
||||
}) {
|
||||
// Example: return an hardcoded list of static sidebar items
|
||||
return [
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue