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);
+}