feat(core): exposed "modulesFileName" option (#647)

typedoc2md · Jul 10, 2024 · a1a8446 · a1a8446
1 parent 3e9d435
commit a1a8446
Show file tree

Hide file tree

Showing 10 changed files with 66 additions and 11 deletions.
diff --git a/devtools/packages/prebuild-options/tasks/generate-docs.ts b/devtools/packages/prebuild-options/tasks/generate-docs.ts
@@ -67,6 +67,7 @@ ${presetsJson}
                   tag.getTagName() !== 'deprecated' &&
                   tag.getTagName() !== 'category' &&
                   tag.getTagName() !== 'omitExample' &&
+                  tag.getTagName() !== 'defaultValue' &&
                   tag.getTagName() !== 'example',
               )
               .map((tag) => ({
@@ -87,6 +88,10 @@ ${presetsJson}
               .getTags()
               .find((tag) => tag.getTagName() === 'deprecated')
               ?.getComment(),
+            default: doc
+              .getTags()
+              .find((tag) => tag.getTagName() === 'defaultValue')
+              ?.getComment(),
             category:
               doc
                 .getTags()
@@ -298,21 +303,30 @@ function getType(option: any) {
 }
 
 function getDefaultValue(option) {
+  if (Boolean(option.default)) {
+    return option.default;
+  }
+
   if (option.type === ParameterType.Boolean) {
     return option.defaultValue;
   }
+
   if (option.type === ParameterType.Flags) {
     return JSON.stringify(option.defaults);
   }
+
   if (option.type === ParameterType.Array) {
     return '';
   }
+
   if (option.type === ParameterType.Mixed) {
     return JSON.stringify(option.defaultValue);
   }
+
   if (option.type === ParameterType.Object) {
     return JSON.stringify(option.defaultValue);
   }
+
   return `"${option.defaultValue}"`;
 }
 

diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx
@@ -16,6 +16,7 @@ Options that are used to configure how files are output.
 - [--flattenOutputFiles](./options/file-options.mdx#--flattenoutputfiles)
 - [--fileExtension](./options/file-options.mdx#--fileextension)
 - [--entryFileName](./options/file-options.mdx#--entryfilename)
+- [--modulesFileName](./options/file-options.mdx#--modulesfilename)
 - [--entryModule](./options/file-options.mdx#--entrymodule)
 - [--excludeScopesInPaths](./options/file-options.mdx#--excludescopesinpaths)
 - [--mergeReadme](./options/file-options.mdx#--mergereadme)

diff --git a/docs/pages/docs/options/file-options.mdx b/docs/pages/docs/options/file-options.mdx
@@ -156,6 +156,22 @@ The content of root documentation file will be resolved in the following order:
 }
 ```
 
+## --modulesFileName
+
+<Callout emoji="💡">
+  The file name of the separate modules / index page.
+</Callout>
+
+> Accepts a string value. Defaults to `"modules | packages | globals"`.
+
+Please note this option is not applicable when `--readme` is set to "none" or `--mergeReadme` is set to "true".
+
+```json filename="typedoc.json"
+{
+  "modulesFileName": "documentation"
+}
+```
+
 ## --entryModule
 
 <Callout emoji="💡">

diff --git a/docs/pages/docs/versioning.mdx b/docs/pages/docs/versioning.mdx
@@ -6,20 +6,15 @@ This page should help you understand the versioning rules of the plugin and its
 
 Please note that TypeDoc is still released within the 0.x.x range and may include breaking changes within each minor version release.
 
-For this reason we follow a slightly amended version of semver:
-
-- **Patch** versions will include all bug fixes but might also include non-breaking new features.
-- **Minor** versions will be released in sync with TypeDoc minor versions and will include any necessary API and feature changes to support the new TypeDoc version.
-  All changes will attempt to be made in a backwards compatible manor.
-- **Major** versions will be made if significant and breaking changes to the plugin are made.
+New versions of TypeDoc will be released with a new minor version of the plugin.
 
 ## Node Version
 
 We will follow the Node.js version specified in the TypeDoc `package.json` file.
 
 ## Compatibility Table
 
-| typedoc-plugin-markdown | TypeDoc | Node Version | Release Date |
-| ----------------------- | ------- | ------------ | ------------ |
-| 4.1.x                   | 0.26.x  | >= 18        | 2024-06-22   |
-| 4.0.x                   | 0.25.x  | >= 16        | 2024-05-03   |
+| typedoc-plugin-markdown | TypeDoc | Node Version |
+| ----------------------- | ------- | ------------ |
+| 4.1.x - 4.2.x           | 0.26.x  | >= 18        |
+| 4.0.x                   | 0.25.x  | >= 16        |
diff --git a/packages/typedoc-plugin-markdown/src/_typedoc.d.ts b/packages/typedoc-plugin-markdown/src/_typedoc.d.ts
@@ -29,6 +29,7 @@ declare module 'typedoc' {
       | 'TypeAlias'
     )[];
     mergeReadme: boolean;
+    modulesFileName: string;
     navigationModel: {
       excludeGroups: boolean;
       excludeCategories: boolean;

diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts
@@ -182,6 +182,21 @@ export const entryFileName: Partial<DeclarationOption> = {
   defaultValue: 'README',
 };
 
+/**
+ * Please note this option is not applicable when `--readme` is set to "none" or `--mergeReadme` is set to "true".
+ *
+ * @example "documentation"
+ *
+ * @defaultValue "modules | packages | globals"
+ *
+ * @category File
+ *
+ */
+export const modulesFileName: Partial<DeclarationOption> = {
+  help: 'The file name of the separate modules / index page.',
+  type: ParameterType.String,
+};
+
 /**
  * This option can be used when the root page of the documentation should be a specific module (typically a module named `index`).
  *

diff --git a/packages/typedoc-plugin-markdown/src/theme/base/url-builder.ts b/packages/typedoc-plugin-markdown/src/theme/base/url-builder.ts
@@ -598,6 +598,10 @@ export class UrlBuilder {
     reflection: ProjectReflection | DeclarationReflection,
     isPackages = false,
   ) {
+    const modulesFileName = this.options.getValue('modulesFileName');
+    if (modulesFileName) {
+      return getFileNameWithExtension(modulesFileName, this.fileExtension);
+    }
     if (isPackages) {
       return getFileNameWithExtension('packages', this.fileExtension);
     }

diff --git a/packages/typedoc-plugin-markdown/src/types/options.ts b/packages/typedoc-plugin-markdown/src/types/options.ts
@@ -112,6 +112,11 @@ export interface PluginOptions {
    */
   mergeReadme: boolean;
 
+  /**
+   * The file name of the separate modules / index page.
+   */
+  modulesFileName: string;
+
   /**
    * Configures how the navigation model will be generated.
    */

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts
@@ -70,7 +70,6 @@ const config: Record<string, Fixture> = {
     ],
     commonOptions: {
       plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')],
-      readme: 'none',
       hidePageHeader: true,
       hideBreadcrumbs: true,
       disableSources: true,
@@ -84,6 +83,7 @@ const config: Record<string, Fixture> = {
         navigationModel: {
           excludeFolders: true,
         },
+        modulesFileName: 'documentation.md',
       },
     ],
   },

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
@@ -337,6 +337,7 @@ exports[`Urls should gets Urls for modules parts: outputFileStrategy: members 1`
   "module-2/interfaces/InterfaceB.md",
   "module-2/type-aliases/TypeA.md",
   "module-2/type-aliases/TypeB.md",
+  "modules.md",
   "namespace/README.md",
   "namespace/classes/ClassA.md",
   "namespace/classes/ClassB.md",
@@ -363,6 +364,7 @@ exports[`Urls should gets Urls for modules parts: outputFileStrategy: members 2`
   "README.md",
   "Test.Module.Name.Interface.InterfaceA.md",
   "Test.Module.Name.md",
+  "documentation.md",
   "module-1.submodules.submodule-1.Class.ClassA.md",
   "module-1.submodules.submodule-1.Class.ClassB.md",
   "module-1.submodules.submodule-1.Enumeration.EnumA.md",
@@ -420,6 +422,7 @@ exports[`Urls should gets Urls for modules parts: outputFileStrategy: modules 1`
   "module-1/submodules/submodule-3-with-modules/nested-submodule-1.md",
   "module-1/submodules/submodule-3-with-modules/nested-submodule-2.md",
   "module-2.md",
+  "modules.md",
   "namespace.md",
 ]
 `;
@@ -429,6 +432,7 @@ exports[`Urls should gets Urls for modules parts: outputFileStrategy: modules 2`
   "@scope.namespace.md",
   "README.md",
   "Test.Module.Name.md",
+  "documentation.md",
   "module-1.submodules.submodule-1.md",
   "module-1.submodules.submodule-2.md",
   "module-1.submodules.submodule-3-with-modules.nested-submodule-1.md",