feat: showcase

packages/docusaurus-plugin-showcase/.npmignore

@@ -0,0 +1,3 @@
+.tsbuildinfo*
+tsconfig*
+__tests__

packages/docusaurus-plugin-showcase/README.md

@@ -0,0 +1,7 @@
+# `@docusaurus/plugin-showcase`
+
+Showcase plugin for Docusaurus.
+
+## Usage
+
+See [plugin-showcase documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-showcase).

packages/docusaurus-plugin-showcase/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@docusaurus/plugin-showcase",
+  "version": "3.0.0",
+  "description": "Showcase plugin for Docusaurus.",
+  "main": "lib/index.js",
+  "types": "src/plugin-showcase.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-plugin-showcase"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/core": "3.0.0",
+    "@docusaurus/types": "3.0.0",
+    "@docusaurus/utils": "3.0.0",
+    "@docusaurus/utils-validation": "3.0.0",
+    "fs-extra": "^11.1.1",
+    "js-yaml": "^4.1.0",
+    "tslib": "^2.6.0",
+    "webpack": "^5.88.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

packages/docusaurus-plugin-showcase/src/index.ts

@@ -0,0 +1,257 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import {
+  DEFAULT_PLUGIN_ID,
+  addTrailingPathSeparator,
+  aliasedSitePath,
+  docuHash,
+  getFolderContainingFile,
+  getPluginI18nPath,
+  Globby,
+  parseMarkdownFile,
+  aliasedSitePathToRelativePath,
+  createAbsoluteFilePathMatcher,
+} from '@docusaurus/utils';
+import Yaml from 'js-yaml';
+
+import {validateShowcaseFrontMatter} from './options';
+import type {LoadContext, Plugin, RouteMetadata} from '@docusaurus/types';
+import type {PluginOptions, Content} from '@docusaurus/plugin-showcase';
+import type {ShowcaseContentPaths} from './types';
+
+export function getContentPathList(
+  contentPaths: ShowcaseContentPaths,
+): string[] {
+  return [contentPaths.contentPathLocalized, contentPaths.contentPath];
+}
+
+const isMarkdownSource = (source: string) =>
+  source.endsWith('.md') || source.endsWith('.mdx');
+
+export default function pluginContentShowcase(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin<Content | null> {
+  const {siteConfig, siteDir, generatedFilesDir, localizationDir} = context;
+
+  const contentPaths: ShowcaseContentPaths = {
+    contentPath: path.resolve(siteDir, options.path),
+    contentPathLocalized: getPluginI18nPath({
+      localizationDir,
+      pluginName: 'docusaurus-plugin-content-pages',
+      pluginId: options.id,
+    }),
+  };
+
+  const pluginDataDirRoot = path.join(
+    generatedFilesDir,
+    'docusaurus-plugin-showcase',
+  );
+  const dataDir = path.join(pluginDataDirRoot, options.id ?? DEFAULT_PLUGIN_ID);
+
+  return {
+    name: 'docusaurus-plugin-showcase',
+
+    // todo doesn't work
+    // getPathsToWatch() {
+    //   const {include} = options;
+    //   return getContentPathList(contentPaths).flatMap((contentPath) =>
+    //     include.map((pattern) => `${contentPath}/${pattern}`),
+    //   );
+    // },
+
+    async loadContent() {
+      const {include} = options;
+
+      if (!(await fs.pathExists(contentPaths.contentPath))) {
+        return null;
+      }
+
+      // const {baseUrl} = siteConfig;
+      const showcaseFiles = await Globby(include, {
+        cwd: contentPaths.contentPath,
+        ignore: options.exclude,
+      });
+
+      async function processShowcaseSourceFile(relativeSource: string) {
+        // Lookup in localized folder in priority
+        const contentPath = await getFolderContainingFile(
+          getContentPathList(contentPaths),
+          relativeSource,
+        );
+
+        const sourcePath = path.join(contentPath, relativeSource);
+        const aliasedSourcePath = aliasedSitePath(sourcePath, siteDir);
+        if (!isMarkdownSource(sourcePath)) {
+          const rawYaml = await fs.readFile(sourcePath, 'utf-8');
+          const unsafeYaml = Yaml.load(rawYaml) as {[key: string]: unknown};
+          const yaml = validateShowcaseFrontMatter(unsafeYaml);
+          return {
+            type: 'yaml',
+            ...yaml,
+          };
+        }
+        const rawMarkdown = await fs.readFile(sourcePath, 'utf-8');
+        const {frontMatter: unsafeFrontMatter, content} =
+          await parseMarkdownFile({
+            filePath: sourcePath,
+            fileContent: rawMarkdown,
+            parseFrontMatter: siteConfig.markdown?.parseFrontMatter,
+          });
+        const frontMatter = validateShowcaseFrontMatter(unsafeFrontMatter);
+        return {
+          type: 'markdown',
+          ...frontMatter,
+          content,
+          sourcePath: aliasedSourcePath,
+        };
+      }
+
+      async function doProcessShowcaseSourceFile(relativeSource: string) {
+        try {
+          return await processShowcaseSourceFile(relativeSource);
+        } catch (err) {
+          throw new Error(
+            `Processing of page source file path=${relativeSource} failed.`,
+            {cause: err as Error},
+          );
+        }
+      }
+
+      return {
+        website: await Promise.all(
+          showcaseFiles.map(doProcessShowcaseSourceFile),
+        ),
+      };
+    },
+
+    async contentLoaded({content, actions}) {
+      if (!content) {
+        return;
+      }
+
+      const {addRoute, createData} = actions;
+
+      function createPageRouteMetadata(
+        metadata: Content['website'][number],
+      ): RouteMetadata {
+        return {
+          sourceFilePath: aliasedSitePathToRelativePath(metadata.sourcePath!),
+          // TODO add support for last updated date in the page plugin
+          //  at least for Markdown files
+          // lastUpdatedAt: metadata.lastUpdatedAt,
+          lastUpdatedAt: undefined,
+        };
+      }
+
+      await Promise.all(
+        content.website.map(async (item) => {
+          if (item.type === 'yaml') {
+            return;
+          }
+          await createData(
+            `${docuHash(item.sourcePath!)}.json`,
+            JSON.stringify(item),
+          );
+
+          const routeMetadata = createPageRouteMetadata(item);
+
+          const mdxPath = aliasedSitePathToRelativePath(item.sourcePath!);
+          console.log('mdxPath', mdxPath);
+
+          addRoute({
+            path: `/showcaseAll/${item.title}`,
+            component: '@theme/ShowcaseDetails',
+            metadata: routeMetadata,
+            modules: {
+              content: item.sourcePath!,
+            },
+            exact: true,
+          });
+        }),
+      );
+
+      const showcaseAllData = await createData(
+        'showcaseAll.json',
+        JSON.stringify(content.website),
+      );
+
+      addRoute({
+        path: '/showcaseAll',
+        component: '@theme/Showcase',
+        modules: {
+          content: showcaseAllData,
+        },
+        exact: true,
+      });
+    },
+
+    configureWebpack() {
+      const contentDirs = getContentPathList(contentPaths);
+
+      return {
+        resolve: {
+          alias: {
+            '~showcase': pluginDataDirRoot,
+          },
+        },
+        module: {
+          rules: [
+            {
+              test: /\.mdx?$/i,
+              include: contentDirs
+                // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+                .map(addTrailingPathSeparator),
+              use: [
+                {
+                  loader: require.resolve('@docusaurus/mdx-loader'),
+                  options: {
+                    staticDirs: siteConfig.staticDirectories.map((dir) =>
+                      path.resolve(siteDir, dir),
+                    ),
+                    siteDir,
+                    isMDXPartial: createAbsoluteFilePathMatcher(
+                      options.exclude,
+                      contentDirs,
+                    ),
+                    metadataPath: (mdxPath: string) => {
+                      // Note that metadataPath must be the same/in-sync as
+                      // the path from createData for each MDX.
+                      const aliasedPath = aliasedSitePath(mdxPath, siteDir);
+                      return path.join(
+                        dataDir,
+                        `${docuHash(aliasedPath)}.json`,
+                      );
+                    },
+                    // Assets allow to convert some relative images paths to
+                    // require() calls
+                    createAssets: ({
+                      frontMatter,
+                    }: {
+                      frontMatter: Content['website'][number];
+                    }) => ({
+                      image: frontMatter.preview,
+                    }),
+                    markdownConfig: siteConfig.markdown,
+                  },
+                },
+                {
+                  loader: path.resolve(__dirname, './markdownLoader.js'),
+                },
+              ].filter(Boolean),
+            },
+          ],
+        },
+      };
+    },
+  };
+}
+
+export {validateOptions} from './options';

packages/docusaurus-plugin-showcase/src/markdownLoader.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {LoaderContext} from 'webpack';
+
+export default function markdownLoader(
+  this: LoaderContext<undefined>,
+  fileString: string,
+): void {
+  const callback = this.async();
+
+  // const options = this.getOptions();
+
+  // TODO provide additional md processing here? like interlinking pages?
+  // fileString = linkify(fileString)
+
+  return callback(null, fileString);
+}

packages/docusaurus-plugin-showcase/src/options.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  Joi,
+  validateFrontMatter,
+  RouteBasePathSchema,
+} from '@docusaurus/utils-validation';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+import type {OptionValidationContext} from '@docusaurus/types';
+import type {
+  PluginOptions,
+  Options,
+  ShowcaseFrontMatter,
+} from '@docusaurus/plugin-showcase';
+
+export const DEFAULT_OPTIONS: PluginOptions = {
+  id: 'showcase',
+  path: 'src/showcase/website', // Path to data on filesystem, relative to site dir.
+  routeBasePath: '/', // URL Route.
+  include: ['**/*.{yml,yaml,md,mdx}'], // Extensions to include.
+  exclude: GlobExcludeDefault,
+};
+
+const PluginOptionSchema = Joi.object<PluginOptions>({
+  path: Joi.string().default(DEFAULT_OPTIONS.path),
+  routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath),
+  include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
+  exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
+  id: Joi.string().default(DEFAULT_OPTIONS.id),
+});
+
+const contentAuthorsSchema = Joi.object({
+  title: Joi.string().required(),
+  description: Joi.string().required(),
+  preview: Joi.string().required(),
+  website: Joi.string().required(),
+  source: Joi.string().required(),
+  tags: Joi.array().items(Joi.string()).required(),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  const validatedOptions = validate(PluginOptionSchema, options);
+  return validatedOptions;
+}
+
+export function validateShowcaseFrontMatter(frontMatter: {
+  [key: string]: unknown;
+}): ShowcaseFrontMatter {
+  return validateFrontMatter(frontMatter, contentAuthorsSchema);
+}