docusaurus-plugin-generate-schema-docs 1.5.1 → 1.6.0

package/__tests__/__snapshots__/generateEventDocs.anchor.test.js.snap

@@ -4,6 +4,7 @@ exports[`generateEventDocs (oneOf with $anchor) should generate documentation us
 "---
 title: Parent Event Anchor
 description: "This is a parent event with oneOf."
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -25,7 +26,7 @@ exports[`generateEventDocs (oneOf with $anchor) should generate documentation us
 title: Child Event Anchor
 description: "This is a child event with an anchor."
 sidebar_label: Child Event Anchor
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/docs/parent-event-anchor/01-child-event-with-anchor.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';
@@ -54,7 +55,7 @@ exports[`generateEventDocs (oneOf with $anchor) should generate documentation us
 title: Child Event Title
 description: "This is a child event with only a title."
 sidebar_label: Child Event Title
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/docs/parent-event-anchor/02-child-event-title.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';

package/__tests__/__snapshots__/generateEventDocs.nested.test.js.snap

@@ -4,6 +4,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 "---
 title: Parent Event
 description: "undefined"
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/parent-event.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -23,6 +24,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 "---
 title: Child Event
 description: "undefined"
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -44,7 +46,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 title: Grandchild A
 description: undefined
 sidebar_label: Grandchild A
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/docs/parent-event/01-child-event/01-grandchild-a.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';
@@ -73,7 +75,7 @@ exports[`generateEventDocs (nested oneOf) should generate nested documentation c
 title: Grandchild B
 description: undefined
 sidebar_label: Grandchild B
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/docs/parent-event/01-child-event/02-grandchild-b.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';

package/__tests__/__snapshots__/generateEventDocs.test.js.snap

@@ -91,6 +91,7 @@ exports[`generateEventDocs (non-versioned) should generate documentation correct
 "---
 title: Root Choice Event
 description: "An example event that has oneOf at the root level."
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json
 ---
 import SchemaJsonViewer from '@theme/SchemaJsonViewer';
 
@@ -112,7 +113,7 @@ exports[`generateEventDocs (non-versioned) should generate documentation correct
 title: Option A
 description: "An example event that has oneOf at the root level."
 sidebar_label: Option A
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/docs/root-choice-event/01-option-a.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';
@@ -141,7 +142,7 @@ exports[`generateEventDocs (non-versioned) should generate documentation correct
 title: Option B
 description: "An example event that has oneOf at the root level."
 sidebar_label: Option B
-custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/docs/root-choice-event/02-option-b.json
+custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json
 ---
 
 import SchemaViewer from '@theme/SchemaViewer';

package/__tests__/generateEventDocs.anchor.test.js

@@ -61,11 +61,18 @@ describe('generateEventDocs (oneOf with $anchor)', () => {
       'utf-8',
     );
     expect(childWithAnchor).toMatchSnapshot();
+    // Inline oneOf options (using $anchor for slug) must link to the parent schema file
+    expect(childWithAnchor).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json',
+    );
 
     const childWithTitle = fs.readFileSync(
       path.join(parentDir, '02-child-event-title.mdx'),
       'utf-8',
     );
     expect(childWithTitle).toMatchSnapshot();
+    expect(childWithTitle).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_anchor__/static/schemas/parent-event-anchor.json',
+    );
   });
 });

package/__tests__/generateEventDocs.nested.test.js

@@ -70,11 +70,18 @@ describe('generateEventDocs (nested oneOf)', () => {
       'utf-8',
     );
     expect(grandchildA).toMatchSnapshot();
+    // Nested $ref-based oneOf options must link to the resolved source schema file
+    expect(grandchildA).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json',
+    );
 
     const grandchildB = fs.readFileSync(
       path.join(childDir, '02-grandchild-b.mdx'),
       'utf-8',
     );
     expect(grandchildB).toMatchSnapshot();
+    expect(grandchildB).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures_nested__/static/schemas/child-event.json',
+    );
   });
 });

package/__tests__/generateEventDocs.test.js

@@ -80,11 +80,18 @@ describe('generateEventDocs (non-versioned)', () => {
       'utf-8',
     );
     expect(rootChoiceA).toMatchSnapshot();
+    // Inline oneOf options must link to the parent schema file, not a temp output file
+    expect(rootChoiceA).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json',
+    );
 
     const rootChoiceB = fs.readFileSync(
       path.join(choiceEventDir, '02-option-b.mdx'),
       'utf-8',
     );
     expect(rootChoiceB).toMatchSnapshot();
+    expect(rootChoiceB).toContain(
+      'custom_edit_url: https://github.com/test-org/test-project/edit/main/__fixtures__/static/schemas/root-choice-event.json',
+    );
   });
 });

package/generateEventDocs.js

@@ -14,34 +14,39 @@ async function generateAndWriteDoc(
   outputDir,
   options,
   alreadyMergedSchema = null,
+  editFilePath = null,
 ) {
-  const { organizationName, projectName, siteDir, dataLayerName } = options;
+  const { organizationName, projectName, siteDir, dataLayerName, version } =
+    options;
   const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
-  const PARTIALS_DIR = path.join(siteDir, 'docs/partials');
+
+  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`);
+  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';`;
+    topPartialImport = `import TopPartial from '@site/${relativePartialsDir}/_${eventName}.mdx';`;
     topPartialComponent = '<TopPartial />';
   }
 
   let bottomPartialImport = '';
   let bottomPartialComponent = '';
   if (fs.existsSync(bottomPartialPath)) {
-    bottomPartialImport = `import BottomPartial from '@site/docs/partials/${eventName}_bottom.mdx';`;
+    bottomPartialImport = `import BottomPartial from '@site/${relativePartialsDir}/_${eventName}_bottom.mdx';`;
     bottomPartialComponent = '<BottomPartial />';
   }
 
   const editUrl = `${baseEditUrl}/${path.relative(
     path.join(siteDir, '..'),
-    filePath,
+    editFilePath || filePath,
   )}`;
 
   const mdxContent = SchemaDocTemplate({
@@ -67,6 +72,10 @@ async function generateOneOfDocs(
   outputDir,
   options,
 ) {
+  const { organizationName, projectName, siteDir } = options;
+  const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
+  const editUrl = `${baseEditUrl}/${path.relative(path.join(siteDir, '..'), filePath)}`;
+
   const eventOutputDir = path.join(outputDir, eventName);
   createDir(eventOutputDir);
 
@@ -75,12 +84,13 @@ 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}`;
@@ -91,7 +101,7 @@ async function generateOneOfDocs(
       await generateOneOfDocs(
         prefixedSlug,
         processedSchema,
-        tempFilePath,
+        sourceFilePath || filePath,
         eventOutputDir,
         options,
       );
@@ -106,6 +116,7 @@ async function generateOneOfDocs(
         eventOutputDir,
         options,
         processedSchema,
+        sourceFilePath || filePath,
       );
       fs.unlinkSync(tempFilePath);
     }

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",
@@ -12,7 +12,8 @@
     "@apidevtools/json-schema-ref-parser": "^15.1.3",
     "json-schema-merge-allof": "^0.8.1",
     "ajv": "^8.17.1",
-    "ajv-draft-04": "^1.0.0"
+    "ajv-draft-04": "^1.0.0",
+    "ajv-keywords": "^5.1.0"
   },
   "publishConfig": {
     "access": "public",