docusaurus-plugin-generate-schema-docs 1.5.4 → 1.7.0

package/generateEventDocs.js

@@ -7,6 +7,20 @@ import SchemaDocTemplate from './helpers/schema-doc-template.js';
 import ChoiceIndexTemplate from './helpers/choice-index-template.js';
 import processSchema from './helpers/processSchema.js';
 
+function buildEditUrl(organizationName, projectName, siteDir, filePath) {
+  const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
+  return `${baseEditUrl}/${path.relative(path.join(siteDir, '..'), filePath)}`;
+}
+
+function resolvePartial(partialPath, relativePartialsDir, componentPrefix) {
+  if (!fs.existsSync(partialPath)) return { import: '', component: '' };
+  const fileName = path.basename(partialPath);
+  return {
+    import: `import ${componentPrefix} from '@site/${relativePartialsDir}/${fileName}';`,
+    component: `<${componentPrefix} />`,
+  };
+}
+
 async function generateAndWriteDoc(
   filePath,
   schema,
@@ -14,45 +28,45 @@ async function generateAndWriteDoc(
   outputDir,
   options,
   alreadyMergedSchema = null,
+  editFilePath = null,
 ) {
-  const { organizationName, projectName, siteDir, dataLayerName } = options;
-  const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
-  const PARTIALS_DIR = path.join(siteDir, 'docs/partials');
+  const { organizationName, projectName, siteDir, dataLayerName, version } =
+    options;
+
+  const { outputDir: versionOutputDir } = getPathsForVersion(version, siteDir);
+  const PARTIALS_DIR = path.join(versionOutputDir, 'partials');
+  const relativePartialsDir = path.relative(siteDir, PARTIALS_DIR);
 
   const mergedSchema = alreadyMergedSchema || (await processSchema(filePath));
 
   // Check for partials
-  const topPartialPath = path.join(PARTIALS_DIR, `${eventName}.mdx`);
-  const bottomPartialPath = path.join(PARTIALS_DIR, `${eventName}_bottom.mdx`);
-
-  let topPartialImport = '';
-  let topPartialComponent = '';
-  if (fs.existsSync(topPartialPath)) {
-    topPartialImport = `import TopPartial from '@site/docs/partials/${eventName}.mdx';`;
-    topPartialComponent = '<TopPartial />';
-  }
-
-  let bottomPartialImport = '';
-  let bottomPartialComponent = '';
-  if (fs.existsSync(bottomPartialPath)) {
-    bottomPartialImport = `import BottomPartial from '@site/docs/partials/${eventName}_bottom.mdx';`;
-    bottomPartialComponent = '<BottomPartial />';
-  }
-
-  const editUrl = `${baseEditUrl}/${path.relative(
-    path.join(siteDir, '..'),
-    filePath,
-  )}`;
+  const top = resolvePartial(
+    path.join(PARTIALS_DIR, `_${eventName}.mdx`),
+    relativePartialsDir,
+    'TopPartial',
+  );
+  const bottom = resolvePartial(
+    path.join(PARTIALS_DIR, `_${eventName}_bottom.mdx`),
+    relativePartialsDir,
+    'BottomPartial',
+  );
+
+  const editUrl = buildEditUrl(
+    organizationName,
+    projectName,
+    siteDir,
+    editFilePath || filePath,
+  );
 
   const mdxContent = SchemaDocTemplate({
     schema,
     mergedSchema,
     editUrl,
     file: path.basename(filePath),
-    topPartialImport,
-    bottomPartialImport,
-    topPartialComponent,
-    bottomPartialComponent,
+    topPartialImport: top.import,
+    bottomPartialImport: bottom.import,
+    topPartialComponent: top.component,
+    bottomPartialComponent: bottom.component,
     dataLayerName,
   });
 
@@ -67,6 +81,14 @@ async function generateOneOfDocs(
   outputDir,
   options,
 ) {
+  const { organizationName, projectName, siteDir } = options;
+  const editUrl = buildEditUrl(
+    organizationName,
+    projectName,
+    siteDir,
+    filePath,
+  );
+
   const eventOutputDir = path.join(outputDir, eventName);
   createDir(eventOutputDir);
 
@@ -75,39 +97,35 @@ async function generateOneOfDocs(
   const indexPageContent = ChoiceIndexTemplate({
     schema,
     processedOptions: processed,
+    editUrl,
   });
   writeDoc(eventOutputDir, 'index.mdx', indexPageContent);
 
   for (const [
     index,
-    { slug, schema: processedSchema },
+    { slug, schema: processedSchema, sourceFilePath },
   ] of processed.entries()) {
     const subChoiceType = processedSchema.oneOf ? 'oneOf' : null;
     const prefixedSlug = `${(index + 1).toString().padStart(2, '0')}-${slug}`;
 
     if (subChoiceType) {
-      const tempFilePath = path.join(eventOutputDir, `${slug}.json`);
-      fs.writeFileSync(tempFilePath, JSON.stringify(processedSchema, null, 2));
       await generateOneOfDocs(
         prefixedSlug,
         processedSchema,
-        tempFilePath,
+        sourceFilePath || filePath,
         eventOutputDir,
         options,
       );
-      fs.unlinkSync(tempFilePath);
     } else {
-      const tempFilePath = path.join(eventOutputDir, `${prefixedSlug}.json`);
-      fs.writeFileSync(tempFilePath, JSON.stringify(processedSchema, null, 2));
       await generateAndWriteDoc(
-        tempFilePath,
+        `${prefixedSlug}.json`,
         processedSchema,
         slug,
         eventOutputDir,
         options,
         processedSchema,
+        sourceFilePath || filePath,
       );
-      fs.unlinkSync(tempFilePath);
     }
   }
 }

package/helpers/buildExampleFromSchema.js

@@ -30,6 +30,17 @@ const buildExampleFromSchema = (schema) => {
     return buildExampleFromSchema(merged);
   }
 
+  // For conditionals, default to the 'then' branch and recurse.
+  if (schema.if && schema.then) {
+    const newSchema = { ...schema };
+    const thenBranch = newSchema.then;
+    delete newSchema.if;
+    delete newSchema.then;
+    delete newSchema.else;
+    const merged = mergeJsonSchema({ allOf: [newSchema, thenBranch] });
+    return buildExampleFromSchema(merged);
+  }
+
   // If there's an explicit example, use it.
   const exampleValue = getSingleExampleValue(schema);
   if (typeof exampleValue !== 'undefined') {

package/helpers/choice-index-template.js

@@ -1,9 +1,10 @@
 export default function ChoiceIndexTemplate(data) {
-  const { schema, processedOptions } = data;
+  const { schema, processedOptions, editUrl } = data;
 
   return `---
 title: ${schema.title}
 description: "${schema.description}"
+custom_edit_url: ${editUrl}
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 

package/helpers/continuingLinesStyle.js

@@ -0,0 +1,169 @@
+/**
+ * Colors for group bracket lines, indexed by bracketIndex.
+ * Uses Docusaurus CSS custom properties so they adapt to light/dark themes.
+ */
+const BRACKET_COLORS = [
+  'var(--ifm-color-info)',
+  'var(--ifm-color-warning)',
+  'var(--ifm-color-success)',
+];
+
+/**
+ * Returns the right-offset (in rem) for a bracket line.
+ * Brackets are positioned from the right edge of the cell so they appear
+ * on the right side of the table, away from the tree connector lines.
+ *
+ *   B=0 → 0.50 rem from right
+ *   B=1 → 0.75 rem from right
+ *   B=2 → 1.00 rem from right
+ */
+export const getBracketPosition = (bracketIndex) => 0.5 + bracketIndex * 0.25;
+
+export const getBracketColor = (bracketIndex) =>
+  BRACKET_COLORS[bracketIndex % BRACKET_COLORS.length];
+
+/** Width of horizontal cap lines in pixels */
+const CAP_WIDTH = 10;
+
+/** Inset from cell edge for cap lines (so they aren't hidden by table borders) */
+const CAP_INSET = 6;
+
+/** Helper to create a bracket key for Set lookups */
+const bracketKey = (b) => `${b.level}:${b.bracketIndex}`;
+
+/**
+ * Generates inline styles for bracket lines positioned on the right side.
+ * Supports optional horizontal "cap" lines at the top and/or bottom of
+ * brackets to visually delineate where a bracket group starts and ends.
+ *
+ * @param {Array<{level: number, bracketIndex: number}>} groupBrackets - Active bracket groups
+ * @param {object} [caps] - Optional cap configuration
+ * @param {Array<{level: number, bracketIndex: number}>} [caps.starting] - Brackets needing a top cap
+ * @param {Array<{level: number, bracketIndex: number}>} [caps.ending] - Brackets needing a bottom cap
+ * @returns {object} Style object with background gradients
+ */
+export const getBracketLinesStyle = (groupBrackets = [], caps = {}) => {
+  if (groupBrackets.length === 0) return {};
+
+  const startingKeys = new Set((caps.starting || []).map(bracketKey));
+  const endingKeys = new Set((caps.ending || []).map(bracketKey));
+
+  const gradients = [];
+  const sizes = [];
+  const positions = [];
+
+  groupBrackets.forEach((bracket) => {
+    const { bracketIndex } = bracket;
+    const pos = getBracketPosition(bracketIndex);
+    const color = getBracketColor(bracketIndex);
+    const key = bracketKey(bracket);
+    const isStarting = startingKeys.has(key);
+    const isEnding = endingKeys.has(key);
+
+    // Vertical line — shortened when caps are present so it doesn't bleed past them
+    const topInset = isStarting ? CAP_INSET : 0;
+    const bottomInset = isEnding ? CAP_INSET : 0;
+    gradients.push(`linear-gradient(${color}, ${color})`);
+    sizes.push(`1px calc(100% - ${topInset + bottomInset}px)`);
+    positions.push(`right ${pos}rem top ${topInset}px`);
+
+    // Horizontal cap at the top (bracket start) — inset from cell edge
+    if (isStarting) {
+      const capOffset = (CAP_WIDTH - 1) / 2; // center cap on the vertical line
+      gradients.push(`linear-gradient(${color}, ${color})`);
+      sizes.push(`${CAP_WIDTH}px 1px`);
+      positions.push(
+        `right calc(${pos}rem - ${capOffset}px) top ${CAP_INSET}px`,
+      );
+    }
+
+    // Horizontal cap at the bottom (bracket end) — inset from cell edge
+    if (isEnding) {
+      const capOffset = (CAP_WIDTH - 1) / 2;
+      gradients.push(`linear-gradient(${color}, ${color})`);
+      sizes.push(`${CAP_WIDTH}px 1px`);
+      positions.push(
+        `right calc(${pos}rem - ${capOffset}px) bottom ${CAP_INSET}px`,
+      );
+    }
+  });
+
+  return {
+    backgroundImage: gradients.join(', '),
+    backgroundSize: sizes.join(', '),
+    backgroundPosition: positions.join(', '),
+    backgroundRepeat: 'no-repeat',
+  };
+};
+
+/**
+ * Merges two background-gradient style objects into one.
+ * @param {object} style1 - First style object
+ * @param {object} style2 - Second style object
+ * @returns {object} Merged style object
+ */
+export const mergeBackgroundStyles = (style1, style2) => {
+  if (!style2.backgroundImage) return style1;
+  if (!style1.backgroundImage) return { ...style1, ...style2 };
+
+  return {
+    ...style1,
+    backgroundImage: `${style1.backgroundImage}, ${style2.backgroundImage}`,
+    backgroundSize: `${style1.backgroundSize}, ${style2.backgroundSize}`,
+    backgroundPosition: `${style1.backgroundPosition}, ${style2.backgroundPosition}`,
+    backgroundRepeat: 'no-repeat',
+  };
+};
+
+/**
+ * Generates inline styles for continuing hierarchical lines through a row.
+ * Only handles tree connector lines (left side). Bracket lines are separate.
+ * @param {number[]} continuingLevels - Array of ancestor levels that need lines
+ * @param {number} level - Current level of the row
+ * @returns {object} Style object with background gradients
+ */
+export const getContinuingLinesStyle = (continuingLevels = [], level = 0) => {
+  const getLevelPosition = (lvl) => lvl * 1.25 + 0.5;
+
+  const allGradients = [];
+  const allSizes = [];
+  const allPositions = [];
+
+  // Draw continuing lines for all ancestor levels
+  continuingLevels.forEach((lvl) => {
+    const pos = getLevelPosition(lvl);
+    allGradients.push(
+      'linear-gradient(var(--ifm-table-border-color), var(--ifm-table-border-color))',
+    );
+    allSizes.push('1px 100%');
+    allPositions.push(`${pos}rem top`);
+  });
+
+  // Also draw the line for the immediate parent level (level - 1) if level > 0
+  // This connects the rows to their parent property
+  if (level > 0) {
+    const parentPos = getLevelPosition(level - 1);
+    if (!continuingLevels.includes(level - 1)) {
+      allGradients.push(
+        'linear-gradient(var(--ifm-table-border-color), var(--ifm-table-border-color))',
+      );
+      allSizes.push('1px 100%');
+      allPositions.push(`${parentPos}rem top`);
+    }
+  }
+
+  // Calculate indentation based on level
+  const paddingLeft = `${level * 1.25 + 0.5}rem`;
+
+  if (allGradients.length === 0) {
+    return { paddingLeft };
+  }
+
+  return {
+    paddingLeft,
+    backgroundImage: allGradients.join(', '),
+    backgroundSize: allSizes.join(', '),
+    backgroundPosition: allPositions.join(', '),
+    backgroundRepeat: 'no-repeat',
+  };
+};

package/helpers/schema-doc-template.js

@@ -8,6 +8,7 @@ export default function MdxTemplate(data) {
     bottomPartialImport,
     topPartialComponent,
     bottomPartialComponent,
+    dataLayerName,
   } = data;
 
   return `---
@@ -30,11 +31,7 @@ ${topPartialComponent}
 
 <SchemaViewer
   schema={${JSON.stringify(mergedSchema)}}
-  ${
-    data.dataLayerName && data.dataLayerName !== 'undefined'
-      ? ` dataLayerName={'${data.dataLayerName}'}`
-      : ''
-  }
+  ${dataLayerName ? ` dataLayerName={'${dataLayerName}'}` : ''}
 />
 <SchemaJsonViewer schema={${JSON.stringify(schema)}} />
 

package/helpers/schema-processing.js

@@ -25,8 +25,10 @@ export async function processOneOfSchema(schema, filePath) {
 
     for (const option of schema[choiceType]) {
       let resolvedOption = option;
+      let sourceFilePath = null;
       if (option.$ref && !option.$ref.startsWith('#')) {
         const refPath = path.resolve(path.dirname(filePath), option.$ref);
+        sourceFilePath = refPath;
         resolvedOption = await processSchema(refPath);
       }
 
@@ -54,6 +56,7 @@ export async function processOneOfSchema(schema, filePath) {
       processedSchemas.push({
         slug,
         schema: newSchema,
+        sourceFilePath,
       });
     }
   }

package/helpers/schemaToExamples.js

@@ -22,6 +22,25 @@ const findChoicePoints = (subSchema, path = []) => {
   return [...currentChoice, ...nestedChoices];
 };
 
+const findConditionalPoints = (subSchema, path = []) => {
+  if (!subSchema) {
+    return [];
+  }
+
+  const currentConditional =
+    subSchema.if && (subSchema.then || subSchema.else)
+      ? [{ path, schema: subSchema }]
+      : [];
+
+  const nestedConditionals = subSchema.properties
+    ? Object.entries(subSchema.properties).flatMap(([key, propSchema]) =>
+        findConditionalPoints(propSchema, [...path, 'properties', key]),
+      )
+    : [];
+
+  return [...currentConditional, ...nestedConditionals];
+};
+
 const generateExampleForChoice = (rootSchema, path, option) => {
   const schemaVariant = JSON.parse(JSON.stringify(rootSchema));
 
@@ -44,10 +63,43 @@ const generateExampleForChoice = (rootSchema, path, option) => {
   }
 };
 
+const generateConditionalExample = (rootSchema, path, branch) => {
+  const schemaVariant = JSON.parse(JSON.stringify(rootSchema));
+
+  if (path.length === 0) {
+    const branchSchema = schemaVariant[branch];
+    delete schemaVariant.if;
+    delete schemaVariant.then;
+    delete schemaVariant.else;
+    if (branchSchema) {
+      return buildExampleFromSchema(
+        mergeJsonSchema({ allOf: [schemaVariant, branchSchema] }),
+      );
+    }
+    return buildExampleFromSchema(schemaVariant);
+  }
+
+  let target = schemaVariant;
+  for (const segment of path) {
+    target = target[segment];
+  }
+  const branchSchema = target[branch];
+  delete target.if;
+  delete target.then;
+  delete target.else;
+  if (branchSchema) {
+    const merged = mergeJsonSchema({ allOf: [target, branchSchema] });
+    Object.keys(target).forEach((k) => delete target[k]);
+    Object.assign(target, merged);
+  }
+  return buildExampleFromSchema(schemaVariant);
+};
+
 export function schemaToExamples(rootSchema) {
   const choicePoints = findChoicePoints(rootSchema);
+  const conditionalPoints = findConditionalPoints(rootSchema);
 
-  if (choicePoints.length === 0) {
+  if (choicePoints.length === 0 && conditionalPoints.length === 0) {
     const example = buildExampleFromSchema(rootSchema);
     if (example && Object.keys(example).length > 0) {
       return [
@@ -57,7 +109,7 @@ export function schemaToExamples(rootSchema) {
     return [];
   }
 
-  return choicePoints.map(({ path, schema }) => {
+  const choiceExamples = choicePoints.map(({ path, schema }) => {
     const choiceType = schema.oneOf ? 'oneOf' : 'anyOf';
     const propertyName = path.length > 0 ? path[path.length - 1] : 'root';
 
@@ -68,4 +120,25 @@ export function schemaToExamples(rootSchema) {
 
     return { property: propertyName, options };
   });
+
+  const conditionalExamples = conditionalPoints.map(({ path, schema }) => {
+    const options = [];
+
+    if (schema.then) {
+      options.push({
+        title: 'When condition is met',
+        example: generateConditionalExample(rootSchema, path, 'then'),
+      });
+    }
+    if (schema.else) {
+      options.push({
+        title: 'When condition is not met',
+        example: generateConditionalExample(rootSchema, path, 'else'),
+      });
+    }
+
+    return { property: 'conditional', options };
+  });
+
+  return [...choiceExamples, ...conditionalExamples];
 }