@cparra/apexdocs 2.25.0-alpha.9 → 3.0.0-alpha.2

package/dist/cli/generate.js

@@ -5,13 +5,13 @@ var _function = require('fp-ts/function');
 var E = require('fp-ts/Either');
 var TE = require('fp-ts/TaskEither');
 var yaml = require('js-yaml');
+var path = require('path');
 var apexReflection = require('@cparra/apex-reflection');
 var O = require('fp-ts/Option');
 var fastXmlParser = require('fast-xml-parser');
 var Handlebars = require('handlebars');
-var defaults = require('../defaults-DUwru49Q.js');
+var defaults = require('../defaults-jLXD2y8-.js');
 var fs = require('fs');
-var path = require('path');
 var chalk = require('chalk');
 var logUpdate = require('log-update');
 var cosmiconfig = require('cosmiconfig');
@@ -38,9 +38,9 @@ function _interopNamespaceDefault(e) {
 var E__namespace = /*#__PURE__*/_interopNamespaceDefault(E);
 var TE__namespace = /*#__PURE__*/_interopNamespaceDefault(TE);
 var yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
+var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 var O__namespace = /*#__PURE__*/_interopNamespaceDefault(O);
 var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
-var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 var yargs__namespace = /*#__PURE__*/_interopNamespaceDefault(yargs);
 
 function apply(fn, ...front) {
@@ -570,7 +570,7 @@ function singleGroup(headingLevel, groupName, adapter, members, linkGenerator) {
 }
 
 function parsedFilesToRenderableBundle(config, parsedFiles, references) {
-  const referenceFinder = apply(linkGenerator, references);
+  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
   function toReferenceGuide(parsedFiles2) {
     return parsedFiles2.reduce(
       addToReferenceGuide(referenceFinder, config, references),
@@ -604,11 +604,15 @@ function addToReferenceGuide(findLinkFromHome, config, references) {
     return acc;
   };
 }
-const linkGenerator = (references, referenceName) => {
+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.
-    { __type: "link", title: reference.displayName, url: `/${reference.pathFromRoot}` }
+    {
+      __type: "link",
+      title: reference.displayName,
+      url: path__namespace.join("/", documentationRootDir, reference.referencePath)
+    }
   ) : referenceName;
 };
 function getTypeGroup$1(type, config) {
@@ -1194,7 +1198,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)
@@ -1228,7 +1232,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
@@ -1446,10 +1450,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) {
@@ -1641,15 +1647,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)
     });
   }
 }
@@ -1765,7 +1771,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);
     }
   );
 }
@@ -2650,7 +2656,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
@@ -2723,7 +2729,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);
 }
@@ -2859,27 +2865,17 @@ const markdownOptions = {
     array: true,
     alias: "p",
     default: defaults.defaults.scope,
-    describe: "A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled. Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource."
+    describe: "A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled."
   },
   defaultGroupName: {
     type: "string",
     default: defaults.defaults.defaultGroupName,
     describe: "Defines the @group name to be used when a file does not specify it."
   },
-  openApiTitle: {
-    type: "string",
-    default: "Apex REST Api",
-    describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.'
-  },
   namespace: {
     type: "string",
     describe: "The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. If generating an OpenApi definition, it will be added to the file's Server Url."
   },
-  openApiFileName: {
-    type: "string",
-    describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-    default: "openapi"
-  },
   sortMembersAlphabetically: {
     type: "boolean",
     describe: "Whether to sort members alphabetically.",
@@ -2889,6 +2885,11 @@ const markdownOptions = {
     type: "boolean",
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.defaults.includeMetadata
+  },
+  documentationRootDir: {
+    type: "string",
+    describe: "The root directory of the documentation. This is used to generate the correct relative paths.",
+    default: defaults.defaults.documentationRootDir
   }
 };
 
@@ -2955,10 +2956,10 @@ function extractArgs() {
 }
 
 function main() {
-  function cathError(error) {
+  function catchError(error) {
     console.error(error);
     process.exit(1);
   }
-  extractArgs().then((config) => Apexdocs.generate(config).catch(cathError)).catch(cathError);
+  extractArgs().then((config) => Apexdocs.generate(config).catch(catchError)).catch(catchError);
 }
 main();

package/dist/defaults-jLXD2y8-.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const defaults = {
+  targetGenerator: "markdown",
+  targetDir: "./docs/",
+  scope: ["global"],
+  defaultGroupName: "Miscellaneous",
+  includeMetadata: false,
+  sortMembersAlphabetically: false,
+  documentationRootDir: ""
+};
+
+exports.defaults = defaults;

package/dist/index.d.ts

@@ -19,6 +19,7 @@ type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
+  documentationRootDir: string;
 } & Partial<ConfigurableHooks>;
 
 type SourceFileMetadata = {
@@ -32,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;
@@ -41,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;
 };
@@ -63,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.
@@ -93,7 +99,7 @@ type TransformDocPage = (
   doc: DocPageData,
 ) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
 
-type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically'>, 'targetGenerator'>;
+type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'documentationRootDir'>, 'targetGenerator'>;
 declare function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig;
 declare function skip(): Skip;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var defaults = require('./defaults-DUwru49Q.js');
+var defaults = require('./defaults-jLXD2y8-.js');
 
 var __defProp = Object.defineProperty;
 var __defProps = Object.defineProperties;

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

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "2.25.0-alpha.9",
+  "version": "3.0.0-alpha.2",
   "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/args.ts

@@ -26,7 +26,7 @@ function _extractYargs(config?: CosmiconfigResult) {
     .command('markdown', 'Generate documentation from Apex classes as a Markdown site.', (yargs) =>
       yargs.options(markdownOptions),
     )
-    .command('openapi', 'Generate an OpenApi REST specification from Apex classes.')
+    .command('openapi', 'Generate an OpenApi REST specification from Apex classes.') // TODO: Add OpenApi specific options
     .demandCommand()
     .parseSync();
 }

package/src/cli/commands/markdown.ts

@@ -21,30 +21,19 @@ export const markdownOptions: { [key: string]: Options } = {
     default: defaults.scope,
     describe:
       'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
-      'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled. ' +
-      'Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.',
+      'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled.',
   },
   defaultGroupName: {
     type: 'string',
     default: defaults.defaultGroupName,
     describe: 'Defines the @group name to be used when a file does not specify it.',
   },
-  openApiTitle: {
-    type: 'string',
-    default: 'Apex REST Api',
-    describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
-  },
   namespace: {
     type: 'string',
     describe:
       'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
       "If generating an OpenApi definition, it will be added to the file's Server Url.",
   },
-  openApiFileName: {
-    type: 'string',
-    describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-    default: 'openapi',
-  },
   sortMembersAlphabetically: {
     type: 'boolean',
     describe: 'Whether to sort members alphabetically.',
@@ -55,4 +44,9 @@ export const markdownOptions: { [key: string]: Options } = {
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.includeMetadata,
   },
+  documentationRootDir: {
+    type: 'string',
+    describe: 'The root directory of the documentation. This is used to generate the correct relative paths.',
+    default: defaults.documentationRootDir,
+  },
 };

package/src/cli/generate.ts

@@ -3,14 +3,14 @@ import { Apexdocs } from '../application/Apexdocs';
 import { extractArgs } from './args';
 
 function main() {
-  function cathError(error: Error) {
+  function catchError(error: Error) {
     console.error(error);
     process.exit(1);
   }
 
   extractArgs()
-    .then((config) => Apexdocs.generate(config).catch(cathError))
-    .catch(cathError);
+    .then((config) => Apexdocs.generate(config).catch(catchError))
+    .catch(catchError);
 }
 
 main();

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/__test__/test-helpers.ts

@@ -18,5 +18,6 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial
     sortMembersAlphabetically: true,
     referenceGuideTemplate: referenceGuideTemplate,
     ...config,
+    documentationRootDir: '',
   });
 }

package/src/core/markdown/adapters/__tests__/interface-adapter.spec.ts

@@ -15,6 +15,7 @@ const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
   defaultGroupName: 'Miscellaneous',
   referenceGuideTemplate: '',
   sortMembersAlphabetically: false,
+  documentationRootDir: '',
 };
 
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {

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

@@ -5,13 +5,14 @@ import { adaptDescribable } from './documentables';
 import { MarkdownGeneratorConfig } from '../generate-docs';
 import { apply } from '#utils/fp';
 import { Type } from '@cparra/apex-reflection';
+import * as path from 'path';
 
 export function parsedFilesToRenderableBundle(
   config: MarkdownGeneratorConfig,
   parsedFiles: ParsedFile[],
   references: Record<string, DocPageReference>,
 ): RenderableBundle {
-  const referenceFinder = apply(linkGenerator, references);
+  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
 
   function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
     return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
@@ -54,11 +55,20 @@ function addToReferenceGuide(
   };
 }
 
-const linkGenerator = (references: Record<string, DocPageReference>, referenceName: string): StringOrLink => {
+const linkGenerator = (
+  references: Record<string, DocPageReference>,
+  documentationRootDir: string,
+  referenceName: string,
+): StringOrLink => {
   const reference: DocPageReference | undefined = references[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: `/${reference.pathFromRoot}` }
+      {
+        __type: 'link',
+        title: reference.displayName,
+        url: path.join('/', documentationRootDir, reference.referencePath),
+      }
     : referenceName;
 };
 

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/markdown/generate-docs.ts

@@ -42,6 +42,7 @@ export type MarkdownGeneratorConfig = Pick<
   | 'transformDocs'
   | 'transformDocPage'
   | 'transformReference'
+  | 'documentationRootDir'
 > & {
   referenceGuideTemplate: string;
   sortMembersAlphabetically: boolean;

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

@@ -21,6 +21,7 @@ export type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
+  documentationRootDir: string;
 } & Partial<ConfigurableHooks>;
 
 export type UserDefinedOpenApiConfig = {
@@ -54,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;
@@ -63,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;
 };
@@ -99,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.

package/src/defaults.ts

@@ -5,4 +5,5 @@ export const defaults = {
   defaultGroupName: 'Miscellaneous',
   includeMetadata: false,
   sortMembersAlphabetically: false,
+  documentationRootDir: '',
 };

package/src/index.ts

@@ -12,7 +12,12 @@ import { defaults } from './defaults';
 type ConfigurableMarkdownConfig = Omit<
   SetOptional<
     UserDefinedMarkdownConfig,
-    'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically'
+    | 'targetDir'
+    | 'scope'
+    | 'defaultGroupName'
+    | 'includeMetadata'
+    | 'sortMembersAlphabetically'
+    | 'documentationRootDir'
   >,
   'targetGenerator'
 >;