Docusaurus Plugin: Generate Schema Docs

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.

Features

• Automatic Documentation Generation: Generates MDX documentation from your JSON schemas.
• Schema Validation: Validates your schemas against the examples provided within them.
• CLI Commands: Provides CLI commands to generate and validate schema documentation.
• Custom Components: Includes React components to beautifully render your schema documentation.

Installation

npm install --save docusaurus-plugin-generate-schema-docs

Usage

1. 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.

2. Place your JSON schemas in the schemas directory at the root of your project.

CLI Commands

Generate Documentation

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.

Validate Schemas

To validate your schemas, run the following command:

npm run validate-schemas

This will validate the schemas in the schemas directory.

Update Schema IDs

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.

Sync GTM Variables (Optional)

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.

Firebase Snippet Targets

ExampleDataLayer supports Firebase snippet targets for:

• android-firebase-kotlin-sdk
• android-firebase-java-sdk
• ios-firebase-swift-sdk
• ios-firebase-objc-sdk

Mapping rules for generated parameters:

• string -> string parameter
• integer/boolean -> integer/long parameter (true = 1, false = 0)
• number -> double parameter
• items -> non-empty array of flat item objects
• unsupported nested values cause a generation error (no automatic flattening or JSON-string fallback)

Reference docs used for syntax and kept as source of truth:

• https://firebase.google.com/docs/analytics/android/events
• https://firebase.google.com/docs/analytics/ios/events

How it Works

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.

Schema Composition (anyOf, oneOf)

The plugin has special handling for anyOf and oneOf keywords in your JSON schemas.

anyOf

When 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.

oneOf

Similar to anyOf, oneOf will also render a dropdown menu.

oneOf at the Root Level

A 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.

Versioning

This plugin supports documentation and schema versioning, integrated with Docusaurus's native versioning system.

Enabling Versioning

To enable versioning, you need to:

1. Enable Docusaurus Versioning: Follow the Docusaurus documentation to enable versioning for your site. This typically involves creating a versions.json file.

2. 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.

Non-Versioned Mode

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.

Schema $id Versioning

When 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.

Partials

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.

Naming Convention

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.

Location

Place partial files in /docs/partials (or versioned_docs/version-<x>/partials for versioned docs).

The plugin supports two lookup modes:

• Scoped partials (recommended): partials/<doc-subpath>/_my-event.mdx
  Example: docs/partials/event-reference/_add-to-cart-event.mdx
• Basename fallback: partials/_my-event.mdx
  Fallback is only applied when the page/event name is unique. If the same name exists in multiple places, fallback is disabled to avoid accidental cross-page injection.

For authoring MDX content in partials, see the official Docusaurus docs:
https://docusaurus.io/docs/markdown-features/react

Example

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.mdx
• docs/partials/event-reference/_add-to-cart-event_bottom.mdx

Related packages

eslint-plugin-tracking-schema

An 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

Contributing

Contributions are welcome! Please open an issue or submit a pull request if you have any ideas or improvements.

License

This project is licensed under the MIT License.