docusaurus-plugin-generate-schema-docs
Advanced tools
Docusaurus plugin to generate documentation from JSON schemas.
This Docusaurus v2 plugin generates documentation from JSON schemas. It provides a set of tools to automatically create and validate documentation for your event schemas.
npm install --save docusaurus-plugin-generate-schema-docs
Configure the plugin in your docusaurus.config.js:
// docusaurus.config.js
module.exports = {
// ...
plugins: [
[
'docusaurus-plugin-generate-schema-docs',
{
// Options if any
dataLayerName: 'customDataLayer',
},
],
],
// ...
};
The dataLayerName option allows you to customize the name of the data layer variable in the generated examples. If not provided, it defaults to dataLayer.
Place your JSON schemas in the schemas directory at the root of your project.
To generate the documentation from your schemas, run the following command:
npm run gen-docs
This will generate MDX files in the docs/events directory.
To validate your schemas, run the following command:
npm run validate-schemas
This will validate the schemas in the schemas directory.
When using versioning, you can update the $id of your versioned schemas by running:
npm run update-schema-ids
This command will update the $id of all schemas in the versioned directories.
If you use Google Tag Manager, you can sync Data Layer Variables from your schemas:
npm install --save-optional @owntag/gtm-cli
npm run sync:gtm
The Docusaurus CLI command is:
docusaurus sync-gtm
By default, it resolves schemas from the project root. Use --path=<siteDir> to target a different site directory.
Only schemas tagged with x-tracking-targets including web-datalayer-js are used for GTM variable sync. Untagged schemas are ignored.
ExampleDataLayer supports Firebase snippet targets for:
android-firebase-kotlin-sdkandroid-firebase-java-sdkios-firebase-swift-sdkios-firebase-objc-sdkMapping rules for generated parameters:
string -> string parameterinteger/boolean -> integer/long parameter (true = 1, false = 0)number -> double parameteritems -> non-empty array of flat item objectsReference docs used for syntax and kept as source of truth:
The plugin reads your JSON schemas, dereferences any $ref properties, and merges allOf properties. It then generates an MDX file for each schema, which uses custom React components to render the schema details.
The validation script builds an example from each schema and validates it against the schema itself, ensuring your examples are always in sync with your schemas.
The plugin has special handling for anyOf and oneOf keywords in your JSON schemas.
anyOfWhen anyOf is used, the plugin will render a dropdown menu in the documentation that allows users to switch between the different sub-schemas. This is useful for representing properties that can have multiple different structures.
oneOfSimilar to anyOf, oneOf will also render a dropdown menu.
oneOf at the Root LevelA special behavior is triggered when oneOf is used at the root level of a schema file. If a schema's top-level definition is a oneOf array, the plugin will generate a directory structure that reflects the choices.
For example, given a schema my-event.json with a oneOf at the root, where each item in the oneOf array is a reference to another schema file (e.g., option-a.json, option-b.json), the plugin will generate the following structure:
docs/events/my-event/: A directory for the parent schema.docs/events/my-event/index.mdx: An index page for my-event.docs/events/my-event/option-a.mdx: A page for the first option.docs/events/my-event/option-b.mdx: A page for the second option.This creates a nested navigation structure in Docusaurus, which is useful for grouping related events or entities under a single menu item.
This plugin supports documentation and schema versioning, integrated with Docusaurus's native versioning system.
To enable versioning, you need to:
Enable Docusaurus Versioning: Follow the Docusaurus documentation to enable versioning for your site. This typically involves creating a versions.json file.
Organize Your Schemas: Create a versioned directory structure for your schemas. Instead of placing your schemas in static/schemas, you should have:
static/schemas/next: For the "current" or "next" version of your schemas.static/schemas/<version>: For each version of your schemas (e.g., static/schemas/1.1.1).When versioning is enabled, the plugin will automatically detect the versions.json file and generate documentation for each version, as well as for the current version.
If you do not have a versions.json file in your siteDir, the plugin will run in non-versioned mode. It will read your schemas from static/schemas and generate documentation in docs/events.
$id VersioningWhen using the versioning feature, the plugin will automatically update the $id of your schemas to include the version number. For example, if your site's url is https://example.com and you have a schema my-event.json in version 1.0.0, the $id will be updated to https://example.com/schemas/1.0.0/my-event.json.
This is done automatically by the plugin. However, if you need to update the $ids of your schemas manually, you can use the update-schema-ids.js script located in the plugin's helpers directory.
You can provide additional content to the generated documentation pages by creating partial files. Partials are Markdown files that can be automatically included in the generated pages.
Partials must be named after the generated page/event name and prefixed with an underscore. For a page/event named my-event, the partials are:
_my-event.mdx: Rendered directly after the page description._my-event_bottom.mdx: Rendered at the very bottom of the page.Place partial files in /docs/partials (or versioned_docs/version-<x>/partials for versioned docs).
The plugin supports two lookup modes:
partials/<doc-subpath>/_my-event.mdxdocs/partials/event-reference/_add-to-cart-event.mdxpartials/_my-event.mdxFor authoring MDX content in partials, see the official Docusaurus docs:
https://docusaurus.io/docs/markdown-features/react
If you have event-reference/add-to-cart-event and mobile-reference/add-to-cart-event, use scoped partials to target only the web page:
docs/partials/event-reference/_add-to-cart-event.mdxdocs/partials/event-reference/_add-to-cart-event_bottom.mdxeslint-plugin-tracking-schemaAn ESLint plugin that enforces annotation quality on the JSON Schema files you feed into this plugin. It ensures every property has a description, a type, and examples — catching incomplete schemas at author time before they produce misleading documentation.
npm install --save-dev eslint-plugin-tracking-schema jsonc-eslint-parser
Contributions are welcome! Please open an issue or submit a pull request if you have any ideas or improvements.
This project is licensed under the MIT License.
FAQs
Docusaurus plugin to generate documentation from JSON schemas.
We found that docusaurus-plugin-generate-schema-docs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.