@cparra/apexdocs 3.0.0-alpha.2 → 3.0.0-alpha.4

package/dist/cli/generate.js

@@ -10,7 +10,7 @@ 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-jLXD2y8-.js');
+var defaults = require('../defaults-DGKfeZq-.js');
 var fs = require('fs');
 var chalk = require('chalk');
 var logUpdate = require('log-update');
@@ -569,17 +569,68 @@ function singleGroup(headingLevel, groupName, adapter, members, linkGenerator) {
   };
 }
 
+const generateLink = (strategy) => {
+  switch (strategy) {
+    case "relative":
+      return generateRelativeLink;
+    case "no-link":
+      return generateNoLink;
+    case "none":
+      return returnReferenceAsIs;
+  }
+};
+const generateRelativeLink = (references, from, referenceName) => {
+  function getRelativePath(fromPath, toPath) {
+    return path.relative(path.parse(path.join("/", fromPath)).dir, path.join("/", toPath));
+  }
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  if (referenceTo && from === "__base__") {
+    return {
+      __type: "link",
+      title: referenceTo.displayName,
+      url: getRelativePath("", referenceTo.referencePath)
+    };
+  }
+  const referenceFrom = references[from];
+  if (!referenceFrom) {
+    return referenceTo.displayName;
+  }
+  return {
+    __type: "link",
+    title: referenceTo.displayName,
+    url: getRelativePath(referenceFrom.referencePath, referenceTo.referencePath)
+  };
+};
+const generateNoLink = (references, _from, referenceName) => {
+  const referenceTo = references[referenceName];
+  return referenceTo ? referenceTo.displayName : referenceName;
+};
+const returnReferenceAsIs = (references, _from, referenceName) => {
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  return {
+    __type: "link",
+    title: referenceTo.displayName,
+    url: referenceTo.referencePath
+  };
+};
+
 function parsedFilesToRenderableBundle(config, parsedFiles, references) {
-  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
+  const referenceFinder = apply(generateLink(config.linkingStrategy), references);
   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,17 +655,6 @@ 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.
-    {
-      __type: "link",
-      title: reference.displayName,
-      url: path__namespace.join("/", documentationRootDir, reference.referencePath)
-    }
-  ) : referenceName;
-};
 function getTypeGroup$1(type, config) {
   var _a, _b;
   const groupAnnotation = (_a = type.docComment) == null ? void 0 : _a.annotations.find((annotation) => annotation.name.toLowerCase() === "group");
@@ -1705,9 +1745,25 @@ class Logger {
   static clear() {
     logUpdate.clear();
   }
+  static startSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+    }
+    this.spinnerInterval = setInterval(() => {
+      this.logSingle("Processing...", true, "green", true);
+    }, 80);
+  }
+  static stopSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+      this.spinnerInterval = null;
+      this.clear();
+    }
+  }
 }
 Logger.currentFrame = 0;
 Logger.frames = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+Logger.spinnerInterval = null;
 
 const referenceGuideTemplate = `
 # Apex Reference Guide
@@ -2834,14 +2890,19 @@ class Apexdocs {
   static generate(config) {
     return __async$1(this, null, function* () {
       Logger.logSingle("Initializing...", false);
-      const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
-      switch (config.targetGenerator) {
-        case "markdown":
-          yield generate(fileBodies, config);
-          break;
-        case "openapi":
-          openApi(fileBodies, config);
-          break;
+      Logger.startSpinner();
+      try {
+        const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
+        switch (config.targetGenerator) {
+          case "markdown":
+            yield generate(fileBodies, config);
+            break;
+          case "openapi":
+            openApi(fileBodies, config);
+            break;
+        }
+      } finally {
+        Logger.stopSpinner();
       }
     });
   }
@@ -2886,10 +2947,11 @@ const markdownOptions = {
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.defaults.includeMetadata
   },
-  documentationRootDir: {
+  linkingStrategy: {
     type: "string",
-    describe: "The root directory of the documentation. This is used to generate the correct relative paths.",
-    default: defaults.defaults.documentationRootDir
+    describe: "The strategy to use when linking to other documentation pages.",
+    choices: ["relative", "no-link", "none"],
+    default: defaults.defaults.linkingStrategy
   }
 };
 

package/dist/defaults-DGKfeZq-.js

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

package/dist/index.d.ts

@@ -10,6 +10,17 @@ type ConfigurableHooks = {
   transformReference: TransformReference;
 };
 
+type LinkingStrategy =
+  // Links will be generated using relative paths.
+  | 'relative'
+  // No links will be generated.
+  // If the reference is found, the display name will be used.
+  // Otherwise, the name
+  // of the reference itself will be used.
+  | 'no-link'
+  // No logic will be applied, the reference path will be used as is.
+  | 'none';
+
 type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   sourceDir: string;
@@ -19,7 +30,7 @@ type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
-  documentationRootDir: string;
+  linkingStrategy: LinkingStrategy;
 } & Partial<ConfigurableHooks>;
 
 type SourceFileMetadata = {
@@ -99,7 +110,7 @@ type TransformDocPage = (
   doc: DocPageData,
 ) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
 
-type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'documentationRootDir'>, 'targetGenerator'>;
+type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'>, '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-jLXD2y8-.js');
+var defaults = require('./defaults-DGKfeZq-.js');
 
 var __defProp = Object.defineProperty;
 var __defProps = Object.defineProperties;

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

@@ -5,7 +5,7 @@ ns
 
 **Inheritance**
 
-[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](../miscellaneous/BaseClass.md)
+[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
 
 ## Fields
 ### `sampleEnumFromBase`

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

@@ -6,10 +6,12 @@ This is a sample interface
 
 **Mermaid** 
 
-graph TD 
-A[SampleInterface] -->|extends| B[ParentInterface] 
-B -->|extends| C[GrandParentInterface] 
-C -->|extends| D[GreatGrandParentInterface]
+```mermaid
+graph TD
+   A[SampleInterface] -->|extends| B[ParentInterface]
+   B -->|extends| C[GrandParentInterface]
+   C -->|extends| D[GreatGrandParentInterface]
+```
 
 **Author** John Doe
 
@@ -17,17 +19,19 @@ C -->|extends| D[GreatGrandParentInterface]
 
 **See** [SampleEnum](../sample-enums/SampleEnum.md)
 
-**See** [ReferencedEnum](../miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](ReferencedEnum.md)
 
 ## Namespace
 ns
 
 ## Example
-SampleInterface sampleInterface = new SampleInterface(); 
+```apex
+SampleInterface sampleInterface = new SampleInterface();
 sampleInterface.sampleMethod();
+```
 
 **Extends**
-[ParentInterface](../miscellaneous/ParentInterface.md)
+[ParentInterface](ParentInterface.md)
 
 ## Methods
 ### `sampleMethod()`
@@ -62,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
 

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

@@ -115,7 +115,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. |
 
 ---
@@ -186,7 +186,7 @@ global static Url getCurrentRequestUrl()
 ```
 
 #### Return Type
-**[Url](../miscellaneous/Url.md)**
+**[Url](Url.md)**
 
 The URL of the entire request.
 
@@ -294,7 +294,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/markdown/force-app/classes/SampleInterface.cls

@@ -5,13 +5,17 @@
  * @see SampleEnum
  * @see ReferencedEnum
  * @mermaid
+ * ```mermaid
  * graph TD
  *    A[SampleInterface] -->|extends| B[ParentInterface]
  *    B -->|extends| C[GrandParentInterface]
  *    C -->|extends| D[GreatGrandParentInterface]
+ * ```
  * @example
+ * ```apex
  * SampleInterface sampleInterface = new SampleInterface();
  * sampleInterface.sampleMethod();
+ * ```
  */
 @NamespaceAccessible
 public interface SampleInterface extends ParentInterface {

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.2",
+  "version": "3.0.0-alpha.4",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",

package/src/application/Apexdocs.ts

@@ -15,16 +15,21 @@ export class Apexdocs {
    */
   static async generate(config: UserDefinedConfig): Promise<void> {
     Logger.logSingle('Initializing...', false);
+    Logger.startSpinner();
 
-    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
+    try {
+      const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
 
-    switch (config.targetGenerator) {
-      case 'markdown':
-        await markdown(fileBodies, config);
-        break;
-      case 'openapi':
-        openApi(fileBodies, config);
-        break;
+      switch (config.targetGenerator) {
+        case 'markdown':
+          await markdown(fileBodies, config);
+          break;
+        case 'openapi':
+          openApi(fileBodies, config);
+          break;
+      }
+    } finally {
+      Logger.stopSpinner();
     }
   }
 }

package/src/cli/commands/markdown.ts

@@ -44,9 +44,10 @@ 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: {
+  linkingStrategy: {
     type: 'string',
-    describe: 'The root directory of the documentation. This is used to generate the correct relative paths.',
-    default: defaults.documentationRootDir,
+    describe: 'The strategy to use when linking to other documentation pages.',
+    choices: ['relative', 'no-link', 'none'],
+    default: defaults.linkingStrategy,
   },
 };

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

@@ -268,9 +268,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data).firstDocContains(
-            'This is a description with a [ClassRef](/miscellaneous/ClassRef.md) reference',
-          ),
+          expect(data).firstDocContains('This is a description with a [ClassRef](ClassRef.md) reference'),
         );
       });
 
@@ -304,7 +302,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('[ClassRef](/miscellaneous/ClassRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[ClassRef](ClassRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {

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

@@ -211,7 +211,7 @@ describe('Generates enum documentation', () => {
       expect(result).documentationBundleHasLength(2);
       assertEither(result, (data) => expect(data).firstDocContains('Description'));
       assertEither(result, (data) =>
-        expect(data).firstDocContains('This is a description with a [EnumRef](/miscellaneous/EnumRef.md) reference'),
+        expect(data).firstDocContains('This is a description with a [EnumRef](EnumRef.md) reference'),
       );
     });
 
@@ -245,7 +245,7 @@ describe('Generates enum documentation', () => {
       const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
       expect(result).documentationBundleHasLength(2);
       assertEither(result, (data) => expect(data).firstDocContains('See'));
-      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](/miscellaneous/EnumRef.md)'));
+      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](EnumRef.md)'));
     });
 
     it('displays sees without links when the reference is not found', async () => {

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

@@ -189,9 +189,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data).firstDocContains(
-            'This is a description with a [InterfaceRef](/miscellaneous/InterfaceRef.md) reference',
-          ),
+          expect(data).firstDocContains('This is a description with a [InterfaceRef](InterfaceRef.md) reference'),
         );
       });
 
@@ -225,7 +223,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](/miscellaneous/InterfaceRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](InterfaceRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {

package/src/core/markdown/__test__/generating-reference-guide.spec.ts

@@ -25,10 +25,10 @@ describe('Generates a Reference Guide', () => {
     expect(result).documentationBundleHasLength(2);
 
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](/miscellaneous/MyEnum.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](miscellaneous/MyEnum.md)'),
     );
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](/miscellaneous/MyClass.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](miscellaneous/MyClass.md)'),
     );
   });
 
@@ -174,7 +174,7 @@ describe('Generates a Reference Guide', () => {
     const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
     expect(result).documentationBundleHasLength(2);
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](/group2/MyClass.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](group2/MyClass.md)'),
     );
   });
 });

package/src/core/markdown/__test__/test-helpers.ts

@@ -17,7 +17,7 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial
     defaultGroupName: 'Miscellaneous',
     sortMembersAlphabetically: true,
     referenceGuideTemplate: referenceGuideTemplate,
+    linkingStrategy: 'relative',
     ...config,
-    documentationRootDir: '',
   });
 }

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

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

package/src/core/markdown/adapters/__tests__/link-generator.spec.ts

@@ -0,0 +1,130 @@
+import { generateLink } from '../generate-link';
+
+describe('Generates links', () => {
+  describe('relative', () => {
+    it('generates relative links from the base when found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns a relative path when linking from a file', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+        from: {
+          referencePath: 'b/fromPath',
+          displayName: 'fromName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: '../a/referencePath',
+      });
+    });
+
+    it('returns the display name when the from reference is not found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('no-link', () => {
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns the display name of the reference when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('none', () => {
+    it('returns the path as is when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+  });
+});

package/src/core/markdown/adapters/generate-link.ts

@@ -0,0 +1,82 @@
+import { StringOrLink } from './types';
+import path from 'path';
+import { LinkingStrategy } from '../../shared/types';
+
+export type LinkingStrategyFn = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string,
+  referenceName: string,
+) => StringOrLink;
+
+export const generateLink = (strategy: LinkingStrategy): LinkingStrategyFn => {
+  switch (strategy) {
+    case 'relative':
+      return generateRelativeLink;
+    case 'no-link':
+      return generateNoLink;
+    case 'none':
+      return returnReferenceAsIs;
+  }
+};
+
+const generateRelativeLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string, // The name of the file for which the reference is being generated
+  referenceName: string,
+): StringOrLink => {
+  function getRelativePath(fromPath: string, toPath: string) {
+    return path.relative(path.parse(path.join('/', fromPath)).dir, path.join('/', toPath));
+  }
+
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return 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: getRelativePath('', referenceTo.referencePath),
+    };
+  }
+
+  const referenceFrom = references[from];
+
+  if (!referenceFrom) {
+    return referenceTo.displayName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: getRelativePath(referenceFrom.referencePath, referenceTo.referencePath),
+  };
+};
+
+const generateNoLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  return referenceTo ? referenceTo.displayName : referenceName;
+};
+
+const returnReferenceAsIs = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: referenceTo.referencePath,
+  };
+};

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

@@ -1,29 +1,29 @@
 import { DocPageReference, ParsedFile } from '../../shared/types';
-import { Link, ReferenceGuideReference, Renderable, RenderableBundle, StringOrLink } from './types';
+import { Link, ReferenceGuideReference, Renderable, RenderableBundle } from './types';
 import { typeToRenderable } from './apex-types';
 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';
+import { generateLink } from './generate-link';
 
 export function parsedFilesToRenderableBundle(
   config: MarkdownGeneratorConfig,
   parsedFiles: ParsedFile[],
   references: Record<string, DocPageReference>,
 ): RenderableBundle {
-  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
+  const referenceFinder = apply(generateLink(config.linkingStrategy), references);
 
   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;
     }, []);
@@ -55,23 +55,6 @@ function addToReferenceGuide(
   };
 }
 
-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: path.join('/', documentationRootDir, reference.referencePath),
-      }
-    : referenceName;
-};
-
 function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
   const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
   return groupAnnotation?.body ?? config.defaultGroupName;

package/src/core/markdown/generate-docs.ts

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

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

@@ -12,6 +12,17 @@ export type ConfigurableHooks = {
   transformReference: TransformReference;
 };
 
+type LinkingStrategy =
+  // Links will be generated using relative paths.
+  | 'relative'
+  // No links will be generated.
+  // If the reference is found, the display name will be used.
+  // Otherwise, the name
+  // of the reference itself will be used.
+  | 'no-link'
+  // No logic will be applied, the reference path will be used as is.
+  | 'none';
+
 export type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   sourceDir: string;
@@ -21,7 +32,7 @@ export type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
-  documentationRootDir: string;
+  linkingStrategy: LinkingStrategy;
 } & Partial<ConfigurableHooks>;
 
 export type UserDefinedOpenApiConfig = {

package/src/defaults.ts

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

package/src/index.ts

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

package/src/util/logger.ts

@@ -8,6 +8,7 @@ export class Logger {
   static currentFrame = 0;
 
   static frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  static spinnerInterval: NodeJS.Timeout | null = null;
 
   /**
    * Logs a message with optional arguments.
@@ -54,4 +55,21 @@ export class Logger {
   public static clear() {
     logUpdate.clear();
   }
+
+  public static startSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+    }
+    this.spinnerInterval = setInterval(() => {
+      this.logSingle('Processing...', true, 'green', true);
+    }, 80);
+  }
+
+  public static stopSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+      this.spinnerInterval = null;
+      this.clear();
+    }
+  }
 }