3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-13 00:57:53 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(content-docs): expose isCategoryIndex matcher to customize conventions (#6451)

Browse source 
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
This commit is contained in:
Joshua Chen 2022-01-27 00:58:52 +08:00 • committed by GitHub
parent 76a8d5f38a
commit 24a895fbc5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 408 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -8,7 +8,7 @@
import path from 'path';
import fs from 'fs-extra';
import logger from '@docusaurus/logger';
import {keyBy, last} from 'lodash';
import {keyBy} from 'lodash';
import {
aliasedSitePath,
getEditUrl,
@ -41,6 +41,8 @@ import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
import type {
MetadataOptions,
PluginOptions,
CategoryIndexMatcher,
CategoryIndexMatcherParam,
} from '@docusaurus/plugin-content-docs';
type LastUpdateOptions = Pick<
@ -367,31 +369,62 @@ export function getMainDocId({
return getMainDoc().unversionedId;
}
function getLastPathSegment(str: string): string {
return last(str.split('/'))!;
}
// By convention, Docusaurus considers some docs are "indexes":
// - index.md
// - readme.md
// - <folder>/<folder>.md
//
// This function is the default implementation of this convention
//
// Those index docs produce a different behavior
// - Slugs do not end with a weird "/index" suffix
// - Auto-generated sidebar categories link to them as intro
export function isConventionalDocIndex(doc: {
source: DocMetadataBase['slug'];
sourceDirName: DocMetadataBase['sourceDirName'];
}): boolean {
// "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
const docName = path.parse(doc.source).name;
export const isCategoryIndex: CategoryIndexMatcher = ({
fileName,
directories,
}): boolean => {
const eligibleDocIndexNames = [
'index',
'readme',
directories[0]?.toLowerCase(),
];
return eligibleDocIndexNames.includes(fileName.toLowerCase());
};
// "folder/subFolder/subSubFolder" => "subSubFolder"
const lastDirName = getLastPathSegment(doc.sourceDirName);
export function toCategoryIndexMatcherParam({
source,
sourceDirName,
}: Pick<
DocMetadataBase,
'source' | 'sourceDirName'
>): CategoryIndexMatcherParam {
// source + sourceDirName are always posix-style
return {
fileName: path.posix.parse(source).name,
extension: path.posix.parse(source).ext,
directories: sourceDirName.split(path.posix.sep).reverse(),
};
}
const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
return eligibleDocIndexNames.includes(docName.toLowerCase());
/**
* guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
*/
export function splitPath(str: string): {
/**
* The list of directories, from lowest level to highest.
* If there's no dir name, directories is ['.']
*/
directories: string[];
/** The file name, without extension */
fileName: string;
/** The extension, with a leading dot */
extension: string;
} {
return {
fileName: path.parse(str).name,
extension: path.parse(str).ext,
directories: path.dirname(str).split(path.sep).reverse(),
};
}
// Return both doc ids