Docusaurus plugin to generate JSON-LD structured data (schema.org) for SEO

A Docusaurus plugin that automatically generates JSON-LD structured data (schema.org) for your documentation site's SEO. This plugin scans your markdown/MDX files for front matter schema definitions and generates a React Root component that injects the appropriate structured data into each page.

Features

- 🎯 Automatic Schema Generation: Extracts schema definitions from markdown front matter
- 🌐 JSON-LD Output: Generates valid schema.org JSON-LD for SEO
- 🌍 i18n Support: Handles multilingual sites with locale-specific schemas
- ⚙️ Configurable Paths: Support for custom directory structures
- 🔍 Multiple Schema Types: Support for Article, BlogPosting, Organization, Person, Service, and more
- 🛡️ Error Handling: Graceful error handling and recovery
- 🧪 Fully Tested: Comprehensive Jest test suite with 14+ tests
- 📝 Verbose Logging: Optional detailed logging for debugging
- 🔧 TypeScript: Fully typed with TypeScript interfaces

Installation

``bash
npm install @coffeecup_tech/docusaurus-plugin-structured-data
`

or with yarn:

`bash
yarn add @coffeecup_tech/docusaurus-plugin-structured-data
`

Configuration

Add the plugin to your docusaurus.config.js:

`javascript
module.exports = {
// ... other config
plugins: [
[
'@coffeecup_tech/docusaurus-plugin-structured-data',
{
// Optional: Enable verbose logging
verbose: false,

// Optional: Custom directory paths (relative to siteDir)
srcDir: 'src/pages',
blogDir: 'blog',
docsDir: 'docs',

// Optional: Custom output path for Root.js
outputFile: 'src/theme/Root.js',

// Optional: Fallback image URL for schemas without images
defaultImage: 'https://example.com/default-image.png',

// Base schema for organization/person/website (optional)
baseSchema: {
organization: {
'@id': '${DOCUSAURUS_CONFIG_URL}/#organization',
'@type': 'Organization',
name: 'My Organization',
url: '${DOCUSAURUS_CONFIG_URL}',
logo: '${DOCUSAURUS_CONFIG_URL}/logo.png',
sameAs: '${SAME_AS_DEFAULT}',
},
person: {
'@id': '${DOCUSAURUS_CONFIG_URL}/#person',
'@type': 'Person',
name: 'John Doe',
},
website: {
'@id': '${DOCUSAURUS_CONFIG_URL}/#website',
'@type': 'WebSite',
name: 'My Website',
url: '${DOCUSAURUS_CONFIG_URL}',
},
},

// Optional: i18n specific schemas
i18n: {
fr: {
baseSchema: {
organization: {
'@id': '${DOCUSAURUS_CONFIG_URL}/#organization',
'@type': 'Organization',
name: 'Mon Organisation',
},
},
},
},

// Optional: sameAs default values
sameAsDefault: [
'https://twitter.com/example',
'https://github.com/example',
],
},
],
],
};
`

$3

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| verbose | boolean | false | Enable verbose logging during generation |
| srcDir | string | 'src/pages' | Path to pages directory (relative to siteDir) |
| blogDir | string | 'blog' | Path to blog directory (relative to siteDir) |
| docsDir | string | 'docs' | Path to docs directory (relative to siteDir) |
| outputFile | string | 'src/theme/Root.js' | Path where Root.js will be written |
| defaultImage | string | undefined | Fallback image URL for schemas without images |
| baseSchema | object | undefined | Organization/person/website schema structure |
| i18n | object | undefined | Locale-specific schema overrides |
| sameAsDefault | array | [] | Default sameAs URLs for organization |

Usage

$3

Add a schema object to the front matter of your markdown/MDX files:

`markdown
---
title: My Blog Post
slug: my-blog-post
description: This is a great blog post
image: /img/my-image.png
date: 2024-01-15
schema:
type: BlogPosting
headline: My Blog Post
description: This is a great blog post
image: /img/my-image.png
datePublished: 2024-01-15
dateModified: 2024-01-15
---

My Blog Post

Content here...
`

$3

The plugin automatically enriches the following schema.org types:

- Article - General articles with author/publisher
- BlogPosting - Blog posts with author/publisher
- CollectionPage - Pages that collect other content
- Blog - Blog containers
- AboutPage - About pages
- Service - Services with provider reference
- WebSite - Website metadata
- Organization - Organization information
- Person - Person information

$3

The plugin registers a CLI command with Docusaurus:

`bash
npx docusaurus generate-structured-data
`

This command:
1. Scans all markdown/MDX files in configured directories
2. Extracts schema definitions from front matter
3. Generates a Root.js component with JSON-LD structured data
4. Writes the Root.js file to the specified output path

$3

The plugin automatically adds:
- URL: Current page URL
- mainEntityOfPage: WebPage reference for the current page
- author/publisher: Organization and person references (for Article types)
- provider: Organization reference (for Service types)
- inLanguage: Current locale or 'en-US'

Development

$3

`bash
npm run build
`

Compiles TypeScript from src/ to lib/ directory.

$3

`bash
npm run watch
`

Automatically recompiles on file changes.

$3

`bash


Run all tests

npm test

Run tests in watch mode

npm run test:watch

Generate coverage report

npm run test:coverage
`

The test suite includes:
- Core Functionality Tests: Directory creation, file generation, configuration
- Error Handling Tests: Permission errors, write failures, missing configs
- Schema Generation Tests: JSON-LD validation, type handling, i18n support

$3

A pre-commit hook is configured with Husky to automatically run npm run build before each commit. This ensures the compiled lib/ directory stays in sync with source code.

Simply commit as usual:

`bash
git add src/
git commit -m "Your message"


npm run build runs automatically


`

Examples

$3

`markdown
---
title: Getting Started with Docusaurus
slug: getting-started-docusaurus
description: A comprehensive guide to setting up Docusaurus
image: /img/docusaurus-hero.png
date: 2024-01-10
schema:
type: BlogPosting
headline: Getting Started with Docusaurus
description: A comprehensive guide to setting up Docusaurus
image: /img/docusaurus-hero.png
datePublished: 2024-01-10
dateModified: 2024-01-15
---

Getting Started with Docusaurus

Your content here...
`

$3

`markdown
---
title: API Reference
description: Complete API documentation
schema:
type: Article
headline: API Reference
description: Complete API documentation
---

API Reference

Documentation content...
`

$3

French version (i18n/fr/...):

`markdown
---
title: Commencer avec Docusaurus
schema:
type: BlogPosting
headline: Commencer avec Docusaurus
description: Un guide complet pour configurer Docusaurus
---

Commencer avec Docusaurus

Contenu ici...
`

With the i18n configuration, the plugin will use French-specific schema and locale in the generated JSON-LD.

Architecture

$3

1. Plugin Entry (src/index.ts): Registers the CLI command
2. Generator (src/generator.ts): Main logic that:
- Scans markdown/MDX files in docs, blog, and src/pages
- Extracts front matter schema definitions
- Generates a React Root component
- Injects JSON-LD