Configuration reference

Plugin options

Option	Type	Required	Description
dataDir	string	✓	Directory containing .yaml data files, relative to the Docusaurus site root.
routeBasePath	string	✓	URL path for the showcase page. plugins produces a page at /plugins.
tags	Record<string, TagDef>	✓	Tag definitions. At least one tag is required.
statuses	Record<string, StatusDef>		Status definitions. Omit or pass {} to hide the status filter UI.
id	string		Plugin instance ID - required when registering the plugin more than once in docusaurus.config.ts.
favouriteTag	string		Tag key whose items are surfaced in a highlighted "Our favourites" section above the main grid.
schemaPath	string		Absolute path to a JSON Schema Draft 2020-12 file. Items that fail validation are skipped with a build-time warning.
pageTitle	string		Page <title> and visible heading. Defaults to "Showcase".
pageDescription	string		Sub-heading shown below the page title. Defaults to "A community showcase.".
submitUrl	string		URL for the "Add an item" call-to-action button. Opens in a new tab. Hidden when both this and submitFormPath are omitted. Ignored when submitFormPath is also set.
submitLabel	string		Custom label for the "Add an item" button. Defaults to "Add an item".
submitFormPath	string		Path segment for a built-in submission form. When set, the plugin registers a route at /{routeBasePath}/{submitFormPath} rendering a live form with a card preview and copyable YAML output. The "Add an item" button links to this page instead of submitUrl.
submitGithubRepo	string		GitHub repository in owner/repo format. When set alongside submitFormPath, the form shows a Copy YAML & open GitHub button that copies the generated YAML to the clipboard and opens github.com/{repo}/new/main?filename={dataDir}/{id}.yaml in a new tab, guiding the contributor through a pull-request submission.
schemaUrl	string		Public URL of the JSON Schema for this showcase's data files. Used as the # yaml-language-server: $schema= header in YAML generated by the submission form. The built-in presets set this automatically to a jsDelivr CDN URL.
screenshotUrl	string		URL template used to auto-generate a preview image for items that have no preview field. Use {url} for the percent-encoded site URL or {rawUrl} for the raw URL. Example: https://screenshot.example.com/{url}/thumb. Screenshot generation only applies when website is present.

Preview precedence

Card previews resolve in this order:

1. Explicit preview URL (if provided and non-empty).
2. Generated screenshot from screenshotUrl (when preview is missing and website exists).
3. Placeholder preview (when website is missing).

If the resolved image fails to load, cards fall back to the placeholder preview.

ScreenGrabber recommended settings

If you are using ScreenGrabber as your screenshot service, the following screenshotUrl value is recommended:

https://screengrabber.example.wales/{url}/opengraph/_width:640?format=jpeg

• opengraph — captures at a 1200×630 viewport, which renders the desktop layout of most sites and produces a landscape image that suits the card's aspect ratio.
• _width:640 — resizes the output to 640px wide, retina-crisp at typical card display widths (~350px).
• ?format=jpeg — delivers smaller files than PNG; sufficient quality for site previews.

Replace screengrabber.example.wales with your ScreenGrabber instance hostname.

TagDef

Defines a single tag that items can be assigned and that appears as a filterable chip in the UI.

Field	Type	Required	Description
label	string	✓	Display name shown on the filter chip and on each card.
description	string	✓	Tooltip text shown when hovering the filter chip.
color	string	✓	CSS colour for the tag colour dot (hex, rgb, named, etc.).
icon	string		Lucide icon name rendered beside the tag label.

StatusDef

Defines a single status that an item can be assigned. Statuses are displayed on the card and optionally shown as a filter.

Field	Type	Required	Description
label	string	✓	Display name shown on the card status row.
description	string	✓	Description of what this status means.
color	string		CSS colour for the status indicator dot.
icon	string		Lucide icon name rendered beside the status label.

ShowcaseItem fields

These are the standard fields read from each YAML file. Custom fields are passed through as-is and are accessible in swizzled components.

Field	Type	Description
id	string	Unique identifier for the item.
name	string	Display name shown as the card title.
description	string	Short description shown on the card body.
website	`string \	null`
source	string | null	Source code URL - shown as a "source" button.
preview	string | null	Preview image URL. Overridden by a co-located image if one exists.
author	string | null	Author name shown on the card.
tags	string[]	Array of tag keys defined in the plugin options.
status	string | null	Status key defined in the plugin options.
npmPackages	string[] | null	(Plugins preset) npm package names.
minimumVersion	string | null	(Plugins preset) Minimum Docusaurus version required.