Docusaurus plugin to generate JSON-LD structured data (schema.org) for SEO
npm install @coffeecup_tech/docusaurus-plugin-structured-dataA 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.
- ๐ฏ 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
``bash`
npm install @coffeecup_tech/docusaurus-plugin-structured-data
or with yarn:
`bash`
yarn add @coffeecup_tech/docusaurus-plugin-structured-data
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',
],
},
],
],
};
`
| 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 |
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
---
Content here...
`
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
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
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'
`bash`
npm run build
Compiles TypeScript from src/ to lib/ directory.
`bash`
npm run watch
Automatically recompiles on file changes.
`bashRun all tests
npm test
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