feat(v2): generalize usage of _ prefix convention to exclude content files/folders (#5173)

* create a swizzleWarning partial for shared text

* Generalize usage of _ prefix convention to exclude content files/folders

* add api doc

* MDX loader should not expect metadata/frontmatter on MDX partial files

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/_partials/somePartial.md

@@ -0,0 +1,3 @@
+This is a partial in file/folder starting with _:
+
+It should be excluded by default

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/_partials/subfolder/somePartial.md

@@ -0,0 +1,3 @@
+This is a partial in file/folder starting with _:
+
+It should be excluded by default

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/_somePartial.md

@@ -0,0 +1,3 @@
+This is a partial in file/folder starting with \_:
+
+It should be excluded by default

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.1/_partials/somePartial.md

@@ -0,0 +1,3 @@
+This is a partial in file/folder starting with _:
+
+It should be excluded by default

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.1/_partials/subfolder/somePartial.md

@@ -0,0 +1,3 @@
+This is a partial in file/folder starting with _:
+
+It should be excluded by default

packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/versioned-site/versioned_docs/version-1.0.1/_somePartial.md

@@ -0,0 +1,3 @@
+This is a partial in file/folder starting with \_:
+
+It should be excluded by default

packages/docusaurus-plugin-content-docs/src/__tests__/options.test.ts

@@ -12,6 +12,7 @@ import {
   DefaultNumberPrefixParser,
   DisabledNumberPrefixParser,
 } from '../numberPrefix';
+import {GlobExcludeDefault} from '@docusaurus/utils';
 
 // the type of remark/rehype plugins is function
 const markdownPluginsFunctionStub = () => {};
@@ -30,6 +31,7 @@ describe('normalizeDocsPluginOptions', () => {
       routeBasePath: 'my-docs', // URL Route.
       homePageId: 'home', // Document id for docs home page.
       include: ['**/*.{md,mdx}'], // Extensions to include.
+      exclude: GlobExcludeDefault,
       sidebarPath: 'my-sidebar', // Path to sidebar configuration for showing a list of markdown pages.
       sidebarItemsGenerator: DefaultSidebarItemsGenerator,
       numberPrefixParser: DefaultNumberPrefixParser,

packages/docusaurus-plugin-content-docs/src/docs.ts

@@ -14,6 +14,7 @@ import {
   normalizeUrl,
   parseMarkdownString,
   posixPath,
+  Globby,
 } from '@docusaurus/utils';
 import {LoadContext} from '@docusaurus/types';
 
@@ -28,7 +29,6 @@ import {
 } from './types';
 import getSlug from './slug';
 import {CURRENT_VERSION_NAME} from './constants';
-import globby from 'globby';
 import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './docFrontMatter';
@@ -92,11 +92,12 @@ export async function readVersionDocs(
   versionMetadata: VersionMetadata,
   options: Pick<
     PluginOptions,
-    'include' | 'showLastUpdateAuthor' | 'showLastUpdateTime'
+    'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'
   >,
 ): Promise<DocFile[]> {
-  const sources = await globby(options.include, {
+  const sources = await Globby(options.include, {
     cwd: versionMetadata.contentPath,
+    ignore: options.exclude,
   });
   return Promise.all(
     sources.map((source) => readDocFile(versionMetadata, source, options)),

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -18,6 +18,7 @@ import {
   reportMessage,
   posixPath,
   addTrailingPathSeparator,
+  createMatcher,
 } from '@docusaurus/utils';
 import {LoadContext, Plugin, RouteConfig} from '@docusaurus/types';
 import {loadSidebars, createSidebarsUtils, processSidebars} from './sidebars';
@@ -408,6 +409,7 @@ export default function pluginContentDocs(
                 beforeDefaultRehypePlugins,
                 beforeDefaultRemarkPlugins,
                 staticDir: path.join(siteDir, STATIC_DIR_NAME),
+                isMDXPartial: createMatcher(options.exclude),
                 metadataPath: (mdxPath: string) => {
                   // Note that metadataPath must be the same/in-sync as
                   // the path from createData for each MDX.

packages/docusaurus-plugin-content-docs/src/options.ts

@@ -12,6 +12,8 @@ import {
   AdmonitionsSchema,
   URISchema,
 } from '@docusaurus/utils-validation';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+
 import {OptionValidationContext, ValidationResult} from '@docusaurus/types';
 import chalk from 'chalk';
 import admonitions from 'remark-admonitions';
@@ -26,6 +28,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   routeBasePath: 'docs', // URL Route.
   homePageId: undefined, // TODO remove soon, deprecated
   include: ['**/*.{md,mdx}'], // Extensions to include.
+  exclude: GlobExcludeDefault,
   sidebarItemsGenerator: DefaultSidebarItemsGenerator,
   numberPrefixParser: DefaultNumberPrefixParser,
   docLayoutComponent: '@theme/DocPage',
@@ -66,6 +69,7 @@ export const OptionsSchema = Joi.object({
     .default(DEFAULT_OPTIONS.routeBasePath),
   homePageId: Joi.string().optional(),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
+  exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
   sidebarPath: Joi.alternatives().try(
     Joi.boolean().invalid(true),
     Joi.string(),

packages/docusaurus-plugin-content-docs/src/types.ts

@@ -81,6 +81,7 @@ export type PluginOptions = MetadataOptions &
   RemarkAndRehypePluginOptions & {
     id: string;
     include: string[];
+    exclude: string[];
     docLayoutComponent: string;
     docItemComponent: string;
     admonitions: Record<string, unknown>;