Skip to main content

Getting Started

NPM Version NPM Last Update NPM Downloads

@homotechsual/docusaurus-plugin-showcase builds swizzleable showcase and directory pages from YAML data files. Each item lives in its own .yaml file; the plugin loads them, validates them against an optional JSON Schema, and renders a filterable, searchable page.

Installation​

npm install @homotechsual/docusaurus-plugin-showcase

Choosing an approach​

The plugin ships two ready-made presets for common use cases, and supports fully custom configuration for everything else.

ApproachBest for
Plugins presetA Docusaurus plugin directory - 12 category tags, 3 maintenance statuses.
Sites presetA site showcase, compatible with facebook/docusaurus data files.
Custom showcaseAny other kind of directory: themes, resources, team members, etc.

All three approaches use the same YAML data model and render identical page components. The only difference is which tags, statuses, and schema validation are pre-configured.

Using the plugin more than once​

Register the plugin multiple times to add multiple showcase pages. Each instance beyond the first must have a unique id:

// docusaurus.config.ts
import showcasePlugin, { type PluginOptions as ShowcasePluginOptions } from '@homotechsual/docusaurus-plugin-showcase'
import { pluginsPreset, sitesPreset } from '@homotechsual/docusaurus-plugin-showcase/presets'

export default {
  plugins: [
    [showcasePlugin, {
      ...pluginsPreset,
      dataDir: 'data/plugins',
      routeBasePath: 'plugins',
    } satisfies ShowcasePluginOptions],
    [showcasePlugin, {
      id: 'sites',                 // required for the second instance
      ...sitesPreset,
      dataDir: 'data/sites',
      routeBasePath: 'sites',
    } satisfies ShowcasePluginOptions],
  ],
}

Next steps​