@cparra/apexdocs 3.0.0-alpha.1 → 3.0.0-alpha.3

package/dist/cli/generate.js

@@ -573,13 +573,13 @@ function parsedFilesToRenderableBundle(config, parsedFiles, references) {
   const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
   function toReferenceGuide(parsedFiles2) {
     return parsedFiles2.reduce(
-      addToReferenceGuide(referenceFinder, config, references),
+      addToReferenceGuide(apply(referenceFinder, "__base__"), config, references),
       {}
     );
   }
   function toRenderables(parsedFiles2) {
     return parsedFiles2.reduce((acc, parsedFile) => {
-      const renderable = typeToRenderable(parsedFile, referenceFinder, config);
+      const renderable = typeToRenderable(parsedFile, apply(referenceFinder, parsedFile.source.name), config);
       acc.push(renderable);
       return acc;
     }, []);
@@ -604,16 +604,27 @@ function addToReferenceGuide(findLinkFromHome, config, references) {
     return acc;
   };
 }
-const linkGenerator = (references, documentationRootDir, referenceName) => {
-  const reference = references[referenceName];
-  return reference ? (
-    // Starting the path with a "/" will ensure the link will always be relative to the root of the site.
-    {
+const linkGenerator = (references, documentationRootDir, from, referenceName) => {
+  const referenceTo = references[referenceName];
+  if (referenceTo && from === "__base__") {
+    return {
       __type: "link",
-      title: reference.displayName,
-      url: path__namespace.join("/", documentationRootDir, reference.pathFromRoot)
-    }
-  ) : referenceName;
+      title: referenceTo.displayName,
+      url: path__namespace.join(documentationRootDir, referenceTo.referencePath)
+    };
+  }
+  const referenceFrom = references[from];
+  if (!referenceFrom || !referenceTo) {
+    return referenceName;
+  }
+  const fromPath = path__namespace.parse(path__namespace.join("/", documentationRootDir, referenceFrom.referencePath)).dir;
+  const toPath = path__namespace.join("/", documentationRootDir, referenceTo.referencePath);
+  const relativePath = path__namespace.relative(fromPath, toPath);
+  return {
+    __type: "link",
+    title: referenceTo.displayName,
+    url: relativePath
+  };
 };
 function getTypeGroup$1(type, config) {
   var _a, _b;
@@ -1198,7 +1209,7 @@ const convertToDocumentationBundle = (referenceGuideTemplate, { referencesByGrou
   referenceGuide: {
     frontmatter: null,
     content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
-    filePath: "index.md"
+    outputDocPath: "index.md"
   },
   docs: renderables.map(
     (renderable) => renderableToPageData(Object.values(referencesByGroup).flat(), renderable)
@@ -1232,7 +1243,7 @@ function renderableToPageData(referenceGuideReference, renderable) {
         name: renderable2.name,
         type: renderable2.type
       },
-      filePath: reference.reference.pathFromRoot,
+      outputDocPath: reference.reference.outputDocPath,
       frontmatter: null,
       content: docContents,
       group: (_a = renderable2.doc.group) != null ? _a : defaults.defaults.defaultGroupName
@@ -1450,10 +1461,12 @@ function parsedFilesToReferenceGuide(config, parsedFiles) {
   }, {});
 }
 function parsedFileToDocPageReference(config, parsedFile) {
+  const path = `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`;
   return {
     source: parsedFile.source,
     displayName: parsedFile.type.name,
-    pathFromRoot: `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`
+    outputDocPath: path,
+    referencePath: path
   };
 }
 function getTypeGroup(type, config) {
@@ -1645,15 +1658,15 @@ var __spreadProps$6 = (a, b) => __defProps$6(a, __getOwnPropDescs$6(b));
 class FileWriter {
   static write(files, outputDir, onWriteCallback) {
     files.forEach((file) => {
-      const { filePath, content } = this.getTargetLocation(file, outputDir);
-      fs__namespace.mkdirSync(path__namespace.dirname(filePath), { recursive: true });
-      fs__namespace.writeFileSync(filePath, content, "utf8");
+      const { outputDocPath, content } = this.getTargetLocation(file, outputDir);
+      fs__namespace.mkdirSync(path__namespace.dirname(outputDocPath), { recursive: true });
+      fs__namespace.writeFileSync(outputDocPath, content, "utf8");
       onWriteCallback(file);
     });
   }
   static getTargetLocation(file, outputDir) {
     return __spreadProps$6(__spreadValues$6({}, file), {
-      filePath: path__namespace.join(outputDir, file.filePath)
+      outputDocPath: path__namespace.join(outputDir, file.outputDocPath)
     });
   }
 }
@@ -1769,7 +1782,7 @@ function writeFilesToSystem(files, outputDir) {
     [files.referenceGuide, ...files.docs].filter((file) => !isSkip(file)),
     outputDir,
     (file) => {
-      Logger.logSingle(`${file.filePath} processed.`, false, "green", false);
+      Logger.logSingle(`${file.outputDocPath} processed.`, false, "green", false);
     }
   );
 }
@@ -2654,7 +2667,7 @@ var __spreadProps$1 = (a, b) => __defProps$1(a, __getOwnPropDescs$1(b));
 function createOpenApiFile(fileName, openApiModel) {
   const content = JSON.stringify(__spreadProps$1(__spreadValues$1({}, openApiModel), { namespace: void 0 }), null, 2);
   return {
-    filePath: "",
+    outputDocPath: "",
     content,
     frontmatter: null,
     group: null
@@ -2727,7 +2740,7 @@ function openApi(fileBodies, config) {
   Transpiler.generate(filteredTypes, processor);
   const generatedFiles = processor.fileBuilder().files();
   FileWriter.write(generatedFiles, config.targetDir, (file) => {
-    Logger.logSingle(`${file.filePath} processed.`, false, "green", false);
+    Logger.logSingle(`${file.outputDocPath} processed.`, false, "green", false);
   });
   ErrorLogger.logErrors(filteredTypes);
 }
@@ -2886,7 +2899,7 @@ const markdownOptions = {
   },
   documentationRootDir: {
     type: "string",
-    describe: "The root directory of the documentation. This is used to generate the correct relative paths.",
+    describe: "The root directory of the documentation. This is used to create the correct relative paths when generating links between documents.",
     default: defaults.defaults.documentationRootDir
   }
 };

package/dist/index.d.ts

@@ -33,8 +33,13 @@ type DocPageReference = {
   // The name under which the type should be displayed in the documentation.
   // By default, this will match the source.name, but it can be configured by the user.
   displayName: string;
-  // The location of the file relative to the root of the documentation.
-  pathFromRoot: string;
+  // The location where the file will be written.
+  outputDocPath: string;
+  // The path to the file relative to the documentation root directory. This is used when linking to the file.
+  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
+  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
+  // the path where the file is written.
+  referencePath: string;
 };
 
 type Frontmatter = string | Record<string, unknown> | null;
@@ -42,13 +47,13 @@ type Frontmatter = string | Record<string, unknown> | null;
 type ReferenceGuidePageData = {
   frontmatter: Frontmatter;
   content: string;
-  filePath: string;
+  outputDocPath: string;
 };
 
 type DocPageData = {
   source: SourceFileMetadata;
   group: string | null;
-  filePath: string;
+  outputDocPath: string;
   frontmatter: Frontmatter;
   content: string;
 };
@@ -64,7 +69,7 @@ type Skip = {
 
 type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
 
-type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'filePath'>;
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
 
 /**
  * Allows changing where the files are written to.

package/examples/vitepress/apexdocs.config.ts

@@ -86,7 +86,7 @@ export default defineMarkdownConfig({
 function toSidebarLink(doc: DocPageData) {
   return {
     text: doc.source.name,
-    link: doc.filePath,
+    link: doc.outputDocPath,
   };
 }
 

package/examples/vitepress/docs/index.md

@@ -19,38 +19,38 @@ hero:
 
 ## Miscellaneous
 
-### [BaseClass](/miscellaneous/BaseClass.md)
+### [BaseClass](miscellaneous/BaseClass.md)
 
-### [MultiInheritanceClass](/miscellaneous/MultiInheritanceClass.md)
+### [MultiInheritanceClass](miscellaneous/MultiInheritanceClass.md)
 
-### [ParentInterface](/miscellaneous/ParentInterface.md)
+### [ParentInterface](miscellaneous/ParentInterface.md)
 
-### [ReferencedEnum](/miscellaneous/ReferencedEnum.md)
+### [ReferencedEnum](miscellaneous/ReferencedEnum.md)
 
-### [SampleException](/miscellaneous/SampleException.md)
+### [SampleException](miscellaneous/SampleException.md)
 
 This is a sample exception.
 
-### [SampleInterface](/miscellaneous/SampleInterface.md)
+### [SampleInterface](miscellaneous/SampleInterface.md)
 
 This is a sample interface
 
-### [Url](/miscellaneous/Url.md)
+### [Url](miscellaneous/Url.md)
 
 Represents a uniform resource locator (URL) and provides access to parts of the URL. 
 Enables access to the base URL used to access your Salesforce org.
 
 ## Sample Enums
 
-### [SampleEnum](/sample-enums/SampleEnum.md)
+### [SampleEnum](sample-enums/SampleEnum.md)
 
-This is a sample enum. This references [ReferencedEnum](/miscellaneous/ReferencedEnum.md) . 
+This is a sample enum. This references [ReferencedEnum](miscellaneous/ReferencedEnum.md) . 
  
 This description has several lines
 
 ## SampleGroup
 
-### [SampleClass](/samplegroup/SampleClass.md)
+### [SampleClass](samplegroup/SampleClass.md)
 
 aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
 deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.

package/examples/vitepress/docs/miscellaneous/BaseClass.md

@@ -17,4 +17,4 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](/sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum.md)

package/examples/vitepress/docs/miscellaneous/MultiInheritanceClass.md

@@ -9,7 +9,7 @@ apexdocs
 
 **Inheritance**
 
-[SampleClass](/samplegroup/SampleClass.md) < [BaseClass](/miscellaneous/BaseClass.md)
+[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
 
 ## Fields
 ### `sampleEnumFromBase`
@@ -22,7 +22,7 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](/sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum.md)
 
 ## Properties
 ### Group Name

package/examples/vitepress/docs/miscellaneous/SampleException.md

@@ -9,7 +9,7 @@ This is a sample exception.
 **Usage** 
 
 You can use the exception the following way. 
-You can also take a look at [SampleClass](/samplegroup/SampleClass.md) to see how it is used. 
+You can also take a look at [SampleClass](../samplegroup/SampleClass.md) to see how it is used. 
 This is a dangerous HTML tag: <script>alert('Hello');</script> 
  
 ```apex

package/examples/vitepress/docs/miscellaneous/SampleInterface.md

@@ -19,9 +19,9 @@ C -->|extends| D[GreatGrandParentInterface]
 
 **Date** 2020-01-01
 
-**See** [SampleEnum](/sample-enums/SampleEnum.md)
+**See** [SampleEnum](../sample-enums/SampleEnum.md)
 
-**See** [ReferencedEnum](/miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](ReferencedEnum.md)
 
 ## Namespace
 apexdocs
@@ -31,7 +31,7 @@ SampleInterface sampleInterface = new SampleInterface();
 sampleInterface.sampleMethod();
 
 **Extends**
-[ParentInterface](/miscellaneous/ParentInterface.md)
+[ParentInterface](ParentInterface.md)
 
 ## Methods
 ### `sampleMethod()`
@@ -66,7 +66,7 @@ public String sampleMethod()
 Some return value
 
 #### Throws
-[SampleException](/miscellaneous/SampleException.md): This is a sample exception
+[SampleException](SampleException.md): This is a sample exception
 
 AnotherSampleException: This is another sample exception
 
@@ -94,10 +94,10 @@ public SampleEnum sampleMethodWithParams(String param1, Integer param2, SampleEn
 |------|------|-------------|
 | param1 | String | This is the first parameter |
 | param2 | Integer | This is the second parameter |
-| theEnum | [SampleEnum](/sample-enums/SampleEnum.md) | This is an enum parameter |
+| theEnum | [SampleEnum](../sample-enums/SampleEnum.md) | This is an enum parameter |
 
 #### Return Type
-**[SampleEnum](/sample-enums/SampleEnum.md)**
+**[SampleEnum](../sample-enums/SampleEnum.md)**
 
 Some return value
 

package/examples/vitepress/docs/miscellaneous/Url.md

@@ -120,7 +120,7 @@ global Url(Url context, String spec)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| context | [Url](/miscellaneous/Url.md) | The context in which to parse the specification. |
+| context | [Url](Url.md) | The context in which to parse the specification. |
 | spec | String | The string to parse as a URL. |
 
 ---
@@ -191,7 +191,7 @@ global static Url getCurrentRequestUrl()
 ```
 
 #### Return Type
-**[Url](/miscellaneous/Url.md)**
+**[Url](Url.md)**
 
 The URL of the entire request.
 
@@ -299,7 +299,7 @@ global static Url getOrgDomainUrl()
 ```
 
 #### Return Type
-**[Url](/miscellaneous/Url.md)**
+**[Url](Url.md)**
 
 getOrgDomainUrl() always returns the login URL for your org, regardless of context. Use that URL when making API calls to your org.
 

package/examples/vitepress/docs/sample-enums/SampleEnum.md

@@ -6,13 +6,13 @@ title: SampleEnum
 
 `NAMESPACEACCESSIBLE`
 
-This is a sample enum. This references [ReferencedEnum](/miscellaneous/ReferencedEnum.md) . 
+This is a sample enum. This references [ReferencedEnum](../miscellaneous/ReferencedEnum.md) . 
  
 This description has several lines
 
 **Some Custom** 
 
-Test. I can also have a [ReferencedEnum](/miscellaneous/ReferencedEnum.md) here. 
+Test. I can also have a [ReferencedEnum](../miscellaneous/ReferencedEnum.md) here. 
 And it can be multiline.
 
 **Mermaid** 
@@ -27,7 +27,7 @@ B -->|referenced by| A
 
 **Date** 2022-01-01
 
-**See** [ReferencedEnum](/miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](../miscellaneous/ReferencedEnum.md)
 
 ## Namespace
 apexdocs

package/examples/vitepress/docs/samplegroup/SampleClass.md

@@ -19,12 +19,12 @@ sample.doSomething();
 
 **Inheritance**
 
-[BaseClass](/miscellaneous/BaseClass.md)
+[BaseClass](../miscellaneous/BaseClass.md)
 
 **Implements**
 
-[SampleInterface](/miscellaneous/SampleInterface.md), 
-[ParentInterface](/miscellaneous/ParentInterface.md)
+[SampleInterface](../miscellaneous/SampleInterface.md), 
+[ParentInterface](../miscellaneous/ParentInterface.md)
 
 ## Fields
 ### Group Name
@@ -51,7 +51,7 @@ public sampleEnumFromBase
 ```
 
 ##### Type
-[SampleEnum](/sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum.md)
 
 ## Properties
 ### Group Name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.3",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",

package/src/application/file-writer.ts

@@ -5,9 +5,9 @@ import { PageData } from '../core/shared/types';
 export class FileWriter {
   static write(files: PageData[], outputDir: string, onWriteCallback: (file: PageData) => void) {
     files.forEach((file) => {
-      const { filePath, content } = this.getTargetLocation(file, outputDir);
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, content, 'utf8');
+      const { outputDocPath, content } = this.getTargetLocation(file, outputDir);
+      fs.mkdirSync(path.dirname(outputDocPath), { recursive: true });
+      fs.writeFileSync(outputDocPath, content, 'utf8');
       onWriteCallback(file);
     });
   }
@@ -15,7 +15,7 @@ export class FileWriter {
   private static getTargetLocation(file: PageData, outputDir: string): PageData {
     return {
       ...file,
-      filePath: path.join(outputDir, file.filePath),
+      outputDocPath: path.join(outputDir, file.outputDocPath),
     };
   }
 }

package/src/application/generators/markdown.ts

@@ -48,7 +48,7 @@ function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: strin
       .filter((file) => !isSkip(file)) as PageData[],
     outputDir,
     (file: PageData) => {
-      Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
+      Logger.logSingle(`${file.outputDocPath} processed.`, false, 'green', false);
     },
   );
 }

package/src/application/generators/openapi.ts

@@ -19,7 +19,7 @@ export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDe
   const generatedFiles = processor.fileBuilder().files();
 
   FileWriter.write(generatedFiles, config.targetDir, (file: PageData) => {
-    Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
+    Logger.logSingle(`${file.outputDocPath} processed.`, false, 'green', false);
   });
 
   // Error logging

package/src/cli/commands/markdown.ts

@@ -46,7 +46,8 @@ export const markdownOptions: { [key: string]: Options } = {
   },
   documentationRootDir: {
     type: 'string',
-    describe: 'The root directory of the documentation. This is used to generate the correct relative paths.',
+    describe:
+      'The root directory of the documentation. This is used to create the correct relative paths when generating links between documents.',
     default: defaults.documentationRootDir,
   },
 };

package/src/core/markdown/__test__/generating-class-docs.spec.ts

@@ -12,7 +12,7 @@ describe('Generates interface documentation', () => {
 
       const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].filePath).toContain('MyClass'));
+      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyClass'));
     });
 
     it('returns the type as class', async () => {

package/src/core/markdown/__test__/generating-enum-docs.spec.ts

@@ -17,7 +17,7 @@ describe('Generates enum documentation', () => {
 
       const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].filePath).toContain('MyEnum'));
+      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyEnum'));
     });
 
     it('returns the type as enum', async () => {

package/src/core/markdown/__test__/generating-interface-docs.spec.ts

@@ -453,7 +453,9 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data.docs.find((doc) => doc.filePath.includes('AnotherInterface'))?.content).toContain('Inherited'),
+          expect(data.docs.find((doc) => doc.outputDocPath.includes('AnotherInterface'))?.content).toContain(
+            'Inherited',
+          ),
         );
       });
     });

package/src/core/markdown/adapters/reference-guide.ts

@@ -13,10 +13,12 @@ export function parsedFilesToReferenceGuide(
 }
 
 function parsedFileToDocPageReference(config: MarkdownGeneratorConfig, parsedFile: ParsedFile): DocPageReference {
+  const path = `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`;
   return {
     source: parsedFile.source,
     displayName: parsedFile.type.name,
-    pathFromRoot: `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`,
+    outputDocPath: path,
+    referencePath: path,
   };
 }
 

package/src/core/markdown/adapters/renderable-bundle.ts

@@ -16,14 +16,14 @@ export function parsedFilesToRenderableBundle(
 
   function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
     return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
-      addToReferenceGuide(referenceFinder, config, references),
+      addToReferenceGuide(apply(referenceFinder, '__base__'), config, references),
       {},
     );
   }
 
   function toRenderables(parsedFiles: ParsedFile[]): Renderable[] {
     return parsedFiles.reduce<Renderable[]>((acc, parsedFile) => {
-      const renderable = typeToRenderable(parsedFile, referenceFinder, config);
+      const renderable = typeToRenderable(parsedFile, apply(referenceFinder, parsedFile.source.name), config);
       acc.push(renderable);
       return acc;
     }, []);
@@ -58,18 +58,38 @@ function addToReferenceGuide(
 const linkGenerator = (
   references: Record<string, DocPageReference>,
   documentationRootDir: string,
+  from: string, // The name of the file for which the reference is being generated
   referenceName: string,
 ): StringOrLink => {
-  const reference: DocPageReference | undefined = references[referenceName];
+  const referenceTo: DocPageReference | undefined = references[referenceName];
+  // When linking from the base path (e.g. the reference guide/index page), the reference path is the same as the output
+  // path.
+  if (referenceTo && from === '__base__') {
+    return {
+      __type: 'link',
+      title: referenceTo.displayName,
+      url: path.join(documentationRootDir, referenceTo.referencePath),
+    };
+  }
+
+  const referenceFrom: DocPageReference | undefined = references[from];
+
+  if (!referenceFrom || !referenceTo) {
+    return referenceName;
+  }
 
-  return reference
-    ? // Starting the path with a "/" will ensure the link will always be relative to the root of the site.
-      {
-        __type: 'link',
-        title: reference.displayName,
-        url: path.join('/', documentationRootDir, reference.pathFromRoot),
-      }
-    : referenceName;
+  // Gets the directory of the file that is being linked from.
+  // This is used to calculate the relative path to the file
+  // being linked to.
+  const fromPath = path.parse(path.join('/', documentationRootDir, referenceFrom.referencePath)).dir;
+  const toPath = path.join('/', documentationRootDir, referenceTo.referencePath);
+  const relativePath = path.relative(fromPath, toPath);
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: relativePath,
+  };
 };
 
 function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {

package/src/core/markdown/adapters/renderable-to-page-data.ts

@@ -14,7 +14,7 @@ export const convertToDocumentationBundle = (
   referenceGuide: {
     frontmatter: null,
     content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
-    filePath: 'index.md',
+    outputDocPath: 'index.md',
   },
   docs: renderables.map((renderable: Renderable) =>
     renderableToPageData(Object.values(referencesByGroup).flat(), renderable),
@@ -56,7 +56,7 @@ function renderableToPageData(referenceGuideReference: ReferenceGuideReference[]
         name: renderable.name,
         type: renderable.type,
       },
-      filePath: reference!.reference.pathFromRoot,
+      outputDocPath: reference!.reference.outputDocPath,
       frontmatter: null,
       content: docContents,
       group: renderable.doc.group ?? defaults.defaultGroupName,

package/src/core/openapi/openapi-type-file.ts

@@ -4,7 +4,7 @@ import { OpenApiPageData } from '../shared/types';
 export function createOpenApiFile(fileName: string, openApiModel: OpenApi): OpenApiPageData {
   const content = JSON.stringify({ ...openApiModel, namespace: undefined }, null, 2);
   return {
-    filePath: '',
+    outputDocPath: '',
     content,
     frontmatter: null,
     group: null,

package/src/core/shared/types.d.ts

@@ -55,8 +55,13 @@ export type DocPageReference = {
   // The name under which the type should be displayed in the documentation.
   // By default, this will match the source.name, but it can be configured by the user.
   displayName: string;
-  // The location of the file relative to the root of the documentation.
-  pathFromRoot: string;
+  // The location where the file will be written.
+  outputDocPath: string;
+  // The path to the file relative to the documentation root directory. This is used when linking to the file.
+  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
+  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
+  // the path where the file is written.
+  referencePath: string;
 };
 
 type Frontmatter = string | Record<string, unknown> | null;
@@ -64,13 +69,13 @@ type Frontmatter = string | Record<string, unknown> | null;
 export type ReferenceGuidePageData = {
   frontmatter: Frontmatter;
   content: string;
-  filePath: string;
+  outputDocPath: string;
 };
 
 export type DocPageData = {
   source: SourceFileMetadata;
   group: string | null;
-  filePath: string;
+  outputDocPath: string;
   frontmatter: Frontmatter;
   content: string;
 };
@@ -100,7 +105,7 @@ export type PostHookDocumentationBundle = {
 
 type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
 
-type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'filePath'>;
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
 
 /**
  * Allows changing where the files are written to.