typedoc-plugin-markdown - npm Package Compare versions

Comparing version 4.1.0 to 4.1.1

dist/events/markdown-page-event.d.ts

@@ -36,7 +36,8 @@ import { ProjectReflection, Reflection } from 'typedoc';
     frontmatter?: Record<string, any>;
-    /**
-     * This is required for typing purposes but is unused in the Markdown theme.
-     * @hidden
-     */
+    /** @hidden */
     pageHeadings: any;
+    /** @hidden */
+    pageSections: any;
+    /** @hidden */
+    startNewSection: any;
     /**
@@ -43,0 +44,0 @@ * Triggered before a document will be rendered.

dist/options/declarations.d.ts

@@ -77,2 +77,33 @@ /**
  *
+ * This option will flatten the output files to a single directory as follows:
+ *
+ * Default output:
+ *
+ * ```
+ *   ├── README.md
+ *   ├── module-a/
+ *   │   ├── classes/
+ *   │   │   ├── ClassA.md
+ *   │   │   └── ClassB.md
+ *   │   └── functions/
+ *   │   │   ├── FunctionA.md
+ *   │   │   └── FunctionB.md
+ *   └── module-b/
+ *       └── classes/
+ *           ├── ClassA.md
+ *           └── ClassB.md
+ * ```
+ *
+ * Flattened output:
+ *
+ * ```
+ *   ├── README.md
+ *   ├── module-a.Class.ClassA.md
+ *   ├── module-a.Class.ClassB.md
+ *   ├── module-a.Function.functionA.md
+ *   ├── module-a.Function.functionB.md
+ *   ├── module-b.Class.ClassA.md
+ *   └── module-b.Class.ClassB.md
+ * ```
+ *
  * @category File
@@ -126,2 +157,17 @@ */
  *
+ *  Output when set to `false` (default):
+ *
+ * ```
+ *   └──@scope/
+ *       ├── package-1/
+ *       └── package-2/
+ * ```
+ *
+ * Output when set to `true`:
+ *
+ * ```
+ *   ├── package-1/
+ *   └── package-2/
+ * ```
+ *
  * Ignored if `flattenOutputFiles` is set to `true`.
@@ -128,0 +174,0 @@ *

dist/options/declarations.js

@@ -99,2 +99,33 @@ "use strict";
  *
+ * This option will flatten the output files to a single directory as follows:
+ *
+ * Default output:
+ *
+ * ```
+ *   ├── README.md
+ *   ├── module-a/
+ *   │   ├── classes/
+ *   │   │   ├── ClassA.md
+ *   │   │   └── ClassB.md
+ *   │   └── functions/
+ *   │   │   ├── FunctionA.md
+ *   │   │   └── FunctionB.md
+ *   └── module-b/
+ *       └── classes/
+ *           ├── ClassA.md
+ *           └── ClassB.md
+ * ```
+ *
+ * Flattened output:
+ *
+ * ```
+ *   ├── README.md
+ *   ├── module-a.Class.ClassA.md
+ *   ├── module-a.Class.ClassB.md
+ *   ├── module-a.Function.functionA.md
+ *   ├── module-a.Function.functionB.md
+ *   ├── module-b.Class.ClassA.md
+ *   └── module-b.Class.ClassB.md
+ * ```
+ *
  * @category File
@@ -168,2 +199,17 @@ */
  *
+ *  Output when set to `false` (default):
+ *
+ * ```
+ *   └──@scope/
+ *       ├── package-1/
+ *       └── package-2/
+ * ```
+ *
+ * Output when set to `true`:
+ *
+ * ```
+ *   ├── package-1/
+ *   └── package-2/
+ * ```
+ *
  * Ignored if `flattenOutputFiles` is set to `true`.
@@ -289,4 +335,4 @@ *
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.IndexFormat,
-    defaultValue: maps_1.IndexFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -305,4 +351,4 @@ /**
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.ReflectionFormat,
-    defaultValue: maps_1.ReflectionFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -321,4 +367,4 @@ /**
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.ReflectionFormat,
-    defaultValue: maps_1.ReflectionFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -337,4 +383,4 @@ /**
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.ReflectionFormat,
-    defaultValue: maps_1.ReflectionFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -353,4 +399,4 @@ /**
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.ReflectionFormat,
-    defaultValue: maps_1.ReflectionFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -369,4 +415,4 @@ /**
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.ReflectionFormat,
-    defaultValue: maps_1.ReflectionFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -387,4 +433,4 @@ /**
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.ReflectionFormat,
-    defaultValue: maps_1.ReflectionFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -401,4 +447,4 @@ /**
     type: typedoc_1.ParameterType.Map,
-    map: maps_1.ReflectionFormat,
-    defaultValue: maps_1.ReflectionFormat.List,
+    map: maps_1.DisplayFormat,
+    defaultValue: maps_1.DisplayFormat.List,
 };
@@ -405,0 +451,0 @@ /**

dist/options/maps.d.ts

@@ -14,5 +14,5 @@ /**
 /**
- * The allowed values for formatting reflections.
+ * The allowed values for formatting reflections and indexes.
  */
-export declare enum ReflectionFormat {
+export declare enum DisplayFormat {
     List = "list",
@@ -22,8 +22,1 @@ Table = "table",
 }
-/**
- * The allowed values for formatting indexes.
- */
-export declare enum IndexFormat {
-    List = "list",
-    Table = "table"
-}

dist/options/maps.js

@@ -8,3 +8,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IndexFormat = exports.ReflectionFormat = exports.OutputFileStrategy = void 0;
+exports.DisplayFormat = exports.OutputFileStrategy = void 0;
 /**
@@ -19,17 +19,9 @@ * The allowed values of the `--outputFileStrategy` option.
 /**
- * The allowed values for formatting reflections.
+ * The allowed values for formatting reflections and indexes.
  */
-var ReflectionFormat;
-(function (ReflectionFormat) {
-    ReflectionFormat["List"] = "list";
-    ReflectionFormat["Table"] = "table";
-    ReflectionFormat["HtmlTable"] = "htmlTable";
-})(ReflectionFormat || (exports.ReflectionFormat = ReflectionFormat = {}));
-/**
- * The allowed values for formatting indexes.
- */
-var IndexFormat;
-(function (IndexFormat) {
-    IndexFormat["List"] = "list";
-    IndexFormat["Table"] = "table";
-})(IndexFormat || (exports.IndexFormat = IndexFormat = {}));
+var DisplayFormat;
+(function (DisplayFormat) {
+    DisplayFormat["List"] = "list";
+    DisplayFormat["Table"] = "table";
+    DisplayFormat["HtmlTable"] = "htmlTable";
+})(DisplayFormat || (exports.DisplayFormat = DisplayFormat = {}));

dist/renderer/overrides.js

@@ -39,6 +39,6 @@ "use strict";
     if (this.logger.hasErrors()) {
-        this.logger.error('Documentation could not be generated due to the errors above.');
+        this.logger.error(this.i18n.docs_could_not_be_generated());
     }
     else {
-        this.logger.info(`Documentation generated at ${nicePath(out)}`);
+        this.logger.info(this.i18n.docs_generated_at_0(nicePath(out)));
         this.logger.verbose(`Markdown rendering took ${Date.now() - start}ms`);
@@ -81,12 +81,12 @@ }
     this.preRenderAsyncJobs = [];
+    this.trigger(events_1.MarkdownRendererEvent.BEGIN, output);
     this.application.logger.verbose(`There are ${output.urls?.length} pages to write.`);
     output.urls
-        ?.filter((urlMapping) => urlMapping.model instanceof typedoc_1.ProjectReflection ||
-        urlMapping.model instanceof typedoc_1.DeclarationReflection ||
-        urlMapping.model instanceof typedoc_1.DocumentReflection)
+        ?.filter((urlMapping) => urlMapping.model instanceof typedoc_1.Reflection)
         .forEach(async (urlMapping) => {
         const [template, page] = output.createPageEvent(urlMapping);
+        page.contents = '';
         this.trigger(events_1.MarkdownPageEvent.BEGIN, page);
         if (page.model instanceof typedoc_1.Reflection) {
-            page.contents = this.theme.render(page, template);
+            page.contents = page.contents + this.theme.render(page, template);
         }
@@ -101,3 +101,3 @@ else {
         catch (error) {
-            this.application.logger.error(`Could not write ${page.filename}`);
+            this.application.logger.error(this.application.i18n.could_not_write_0(page.filename));
         }
@@ -104,0 +104,0 @@ });

dist/theme/context/helpers/get-description-for-reflection.js

@@ -9,4 +9,4 @@ "use strict";
     if (comment?.summary?.length) {
-        return this.partials
-            .commentParts(comment.summary)
+        return this.helpers
+            .getCommentParts(comment.summary)
             ?.split('\n\n')[0]
@@ -13,0 +13,0 @@ .replace(/\n/g, ' ');

dist/theme/context/partials/_index.d.ts

 export * from './comments.comment';
-export * from './comments.commentParts';
 export * from './container.body';
@@ -4,0 +3,0 @@ export * from './container.categories';

dist/theme/context/partials/_index.js

@@ -18,3 +18,2 @@ "use strict";
 __exportStar(require("./comments.comment"), exports);
-__exportStar(require("./comments.commentParts"), exports);
 __exportStar(require("./container.body"), exports);
@@ -21,0 +20,0 @@ __exportStar(require("./container.categories"), exports);

dist/theme/context/partials/comments.comment.js

@@ -57,3 +57,3 @@ "use strict";
         }, []);
-        const filteredBlockTags = ['@returns', '@module'];
+        const filteredBlockTags = ['@returns'];
         const tags = blockTags
@@ -70,3 +70,3 @@ .filter((tag) => !filteredBlockTags.includes(tag.tag))
             ];
-            tagMd.push(this.partials.commentParts(tag.content));
+            tagMd.push(this.helpers.getCommentParts(tag.content));
             return tagMd.join('\n');
@@ -73,0 +73,0 @@ });

dist/theme/context/partials/container.categories.js

@@ -12,3 +12,3 @@ "use strict";
         if (category.description) {
-            md.push(this.partials.commentParts(category.description));
+            md.push(this.helpers.getCommentParts(category.description));
         }
@@ -15,0 +15,0 @@ if (category.children) {

dist/theme/context/partials/container.groups.js

@@ -17,3 +17,3 @@ "use strict";
             if (group.description) {
-                md.push(this.partials.commentParts(group.description));
+                md.push(this.helpers.getCommentParts(group.description));
             }
@@ -29,3 +29,3 @@ md.push(this.partials.categories(group.categories, {
             if (group.description) {
-                md.push(this.partials.commentParts(group.description));
+                md.push(this.helpers.getCommentParts(group.description));
             }
@@ -32,0 +32,0 @@ if (isPropertiesGroup &&

dist/theme/context/partials/member.reflectionIndex.js

@@ -12,3 +12,3 @@ "use strict";
             if (categoryGroup.description) {
-                md.push(this.partials.commentParts(categoryGroup.description) + '\n');
+                md.push(this.helpers.getCommentParts(categoryGroup.description) + '\n');
             }
@@ -27,3 +27,3 @@ md.push(this.helpers.getGroupIndex(categoryGroup) + '\n');
                     if (categoryGroup.description) {
-                        md.push(this.partials.commentParts(categoryGroup.description) + '\n');
+                        md.push(this.helpers.getCommentParts(categoryGroup.description) + '\n');
                     }
@@ -30,0 +30,0 @@ md.push(this.helpers.getGroupIndex(categoryGroup) + '\n');

dist/theme/context/partials/member.signature.js

@@ -49,5 +49,4 @@ "use strict";
     }
-    md.push(this.partials.inheritance(model, { headingLevel: options.headingLevel }));
-    if (model.comment) {
-        md.push(this.partials.comment(model.comment, {
+    if (modelComments) {
+        md.push(this.partials.comment(modelComments, {
             headingLevel: options.headingLevel,
@@ -57,2 +56,3 @@ showSummary: false,
     }
+    md.push(this.partials.inheritance(model, { headingLevel: options.headingLevel }));
     if (!options.nested &&
@@ -59,0 +59,0 @@ model.sources &&

dist/theme/context/partials/member.signatureReturns.js

@@ -20,3 +20,3 @@ "use strict";
             .filter((tag) => tag.tag === '@returns')
-            .map((tag) => this.partials.commentParts(tag.content));
+            .map((tag) => this.helpers.getCommentParts(tag.content));
         md.push(tags.join('\n\n'));
@@ -23,0 +23,0 @@ }

dist/theme/context/resources.d.ts

@@ -29,3 +29,2 @@ import { MarkdownPageEvent } from '../../events';
     }) => string;
-    commentParts: (model: CommentDisplayPart[]) => string;
     body: (model: ContainerReflection, options: {
@@ -32,0 +31,0 @@ headingLevel: number;

dist/theme/context/resources.js

@@ -29,3 +29,2 @@ "use strict";
         comment: (model, options = {}) => index_1.partials.comment.apply(context, [model, options]),
-        commentParts: (model) => index_1.partials.commentParts.apply(context, [model]),
         body: (model, options) => index_1.partials.body.apply(context, [model, options]),
@@ -32,0 +31,0 @@ categories: (model, options) => index_1.partials.categories.apply(context, [model, options]),

dist/theme/context/templates/document.js

@@ -15,5 +15,5 @@ "use strict";
     }
-    md.push(this.partials.commentParts(page.model.content));
+    md.push(this.helpers.getCommentParts(page.model.content));
     md.push(this.partials.footer());
     return md.join('\n\n');
 }

dist/theme/context/templates/project.js

@@ -13,3 +13,3 @@ "use strict";
         this.options.getValue('entryPointStrategy') === typedoc_1.EntryPointStrategy.Packages;
-    md.push(this.hook('index.page.begin').join('\n'));
+    md.push(this.hook('index.page.begin', this).join('\n'));
     if (!this.options.getValue('hidePageHeader')) {
@@ -23,3 +23,3 @@ md.push(this.partials.header());
     if (includeReadme && page.model.readme) {
-        md.push(this.partials.commentParts(page.model.readme));
+        md.push(this.helpers.getCommentParts(page.model.readme));
     }
@@ -29,3 +29,3 @@ if (!this.options.getValue('hidePageTitle') && !includeReadme) {
     }
-    md.push(this.hook('content.begin').join('\n'));
+    md.push(this.hook('content.begin', this).join('\n'));
     if (page.model.comment) {
@@ -42,2 +42,5 @@ md.push(this.partials.comment(page.model.comment, { headingLevel: 2 }));
         }
+        if (page.model.children?.some((child) => child.kind !== typedoc_1.ReflectionKind.Module)) {
+            md.push(this.partials.body(page.model, { headingLevel: 2 }));
+        }
         md.push(this.partials.reflectionIndex(page.model, {
@@ -56,4 +59,4 @@ headingLevel: 2,
     md.push(this.partials.footer());
-    md.push(this.hook('index.page.end').join('\n'));
+    md.push(this.hook('index.page.end', this).join('\n'));
     return md.join('\n\n');
 }

dist/theme/context/templates/read-me.js

@@ -16,3 +16,3 @@ "use strict";
     if (Boolean(page.model.readme)) {
-        md.push(this.partials.commentParts(page.model.readme));
+        md.push(this.helpers.getCommentParts(page.model.readme));
     }
@@ -19,0 +19,0 @@ md.push(this.partials.footer());

dist/theme/context/templates/reflection.js

@@ -11,3 +11,3 @@ "use strict";
     const md = [];
-    md.push(this.hook('page.begin').join('\n'));
+    md.push(this.hook('page.begin', this).join('\n'));
     if (!this.options.getValue('hidePageHeader')) {
@@ -22,3 +22,3 @@ md.push(this.partials.header());
     }
-    md.push(this.hook('content.begin').join('\n'));
+    md.push(this.hook('content.begin', this).join('\n'));
     if ([
@@ -37,4 +37,4 @@ typedoc_1.ReflectionKind.Module,
     md.push(this.partials.footer());
-    md.push(this.hook('page.end').join('\n'));
+    md.push(this.hook('page.end', this).join('\n'));
     return md.join('\n\n');
 }

dist/theme/markdown-themeContext.d.ts

 import { MarkdownPageEvent } from '../events';
 import { MarkdownTheme } from '../theme';
-import { MarkdownRendererHooks, PackageMetaData } from '../types';
+import { MarkdownRenderer, PackageMetaData } from '../types';
 import { Internationalization, Options, Reflection } from 'typedoc';
@@ -105,3 +105,2 @@ /**
         }) => string;
-        commentParts: (model: import("typedoc").CommentDisplayPart[]) => string;
         body: (model: import("typedoc").ContainerReflection, options: {
@@ -283,3 +282,3 @@ headingLevel: number;
      */
-    hook: (name: keyof MarkdownRendererHooks) => string[];
+    hook: MarkdownRenderer['markdownHooks']['emit'];
 }

dist/theme/markdown-themeContext.js

@@ -118,3 +118,5 @@ "use strict";
          */
-        this.hook = (name) => this.theme.owner.markdownHooks.emit(name, this);
+        this.hook = (...params) => {
+            return this.theme.owner.markdownHooks.emit(...params);
+        };
         this.packagesMetaData = this.theme.owner.packagesMeta;
@@ -150,3 +152,3 @@ this.internationalization = theme.application.internationalization;
             if (publicPath && !ignorePublicPath) {
-                return encodeURI(path.join(publicPath, url));
+                return encodeURI(path.join(publicPath, url).replace(/\\/g, '/'));
             }
@@ -153,0 +155,0 @@ const baseUrl = path.relative(path.dirname(this.page?.url || '.'), path.dirname(url));

dist/types/markdown-application.d.ts

@@ -1,11 +0,8 @@
-import { Application } from 'typedoc';
+import { Application, Renderer } from 'typedoc';
 import { MarkdownRenderer } from './markdown-renderer';
 /**
- * This interface is essentially an extended typing of TypeDoc's {@linkcode typedoc!Application Application} instance.``
+ * The MarkdownApplication extends TypeDoc's {@linkcode Application} instance with a custom renderer.
  */
 export interface MarkdownApplication extends Application {
-    /**
-     * Re-types the `renderer` instance to {@linkcode MarkdownRenderer }.
-     */
-    renderer: MarkdownRenderer;
+    renderer: MarkdownRenderer & Renderer;
 }

dist/types/markdown-renderer.d.ts

@@ -1,28 +0,59 @@
-import { MarkdownRendererEvent } from '../events';
-import { MarkdownTheme } from '../theme';
+import { MarkdownPageEvent, MarkdownRendererEvent } from '../events';
 import { EventHooks, Options, Renderer } from 'typedoc';
+import { MarkdownTheme } from '..';
 import { MarkdownRendererHooks } from './markdown-renderer-hooks';
+type OmitProperties<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
 /**
- * An extended typing of TypeDoc's {@linkcode typedoc!Renderer Renderer} class that includes updated typings for hooks and async jobs.
+ * The MarkdownRenderer extends TypeDoc's Renderer instance with custom hooks and async jobs.
  */
-export interface MarkdownRenderer extends Renderer {
+export interface MarkdownRenderer extends OmitProperties<Renderer, 'preRenderAsyncJobs' | 'postRenderAsyncJobs'> {
     /**
-     * Replaces the event hooks typings the {@linkcode MarkdownRendererHooks} used by the plugin.
+     * @param event - Triggered before or after a document will be rendered.
+     * @param callback - Receives the {@link MarkdownPageEvent} object as an argument.
+     *
+     * @example
+     *
+     * ```ts
+     * app.renderer.on(MarkdownPageEvent.BEGIN, (renderer) => {});
+     * ```
      */
+    on(event: typeof MarkdownPageEvent.BEGIN | typeof MarkdownPageEvent.END, callback: (page: MarkdownPageEvent) => void): void;
+    /**
+     * @param event - Triggered before or after rendering the project.
+     * @param callback - Receives the {@link MarkdownRendererEvent} object as an argument.
+     *
+     * @example
+     *
+     * ```ts
+     * app.renderer.on(MarkdownRendererEvent.BEGIN, (renderer) => {});
+     * ```
+     */
+    on(event: typeof MarkdownRendererEvent.BEGIN | typeof MarkdownRendererEvent.END, callback: (page: MarkdownRendererEvent) => void): void;
+    /**
+     * Define a new theme that can be used to render output.
+     *
+     * @param name - The name of the theme.
+     * @param theme - The theme class to use.
+     */
+    defineTheme: (name: string, theme: new (renderer: Renderer) => MarkdownTheme) => void;
     markdownHooks: EventHooks<MarkdownRendererHooks, string>;
-    /** @internal */
-    packagesMeta: Record<string, {
-        description: string;
-        options: Options;
-    }>;
-    /** @internal */
-    defineTheme: (name: string, theme: new (renderer: MarkdownRenderer) => MarkdownTheme) => void;
     /**
-     * Re-types the returned argument argument to {@linkcode MarkdownRendererEvent}.
+     * A list of async jobs which must be completed before rendering output.
+     *
+     * Note: This array is cleared after calling the contained functions on each call.
      */
     preRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;
     /**
-     * Re-types the returned argument argument to {@linkcode MarkdownRendererEvent}.
+     * A list of async jobs which must be completed after rendering output files but before generation is considered successful.
+     * These functions will be called after all documents have been written to the filesystem.
+     *
+     * Note: This array is cleared after calling the contained functions on each call.
      */
     postRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;
+    /** @internal */
+    packagesMeta: Record<string, {
+        description: string;
+        options: Options;
+    }>;
 }
+export {};

dist/types/options.d.ts

@@ -68,3 +68,3 @@ /**
      */
-    indexFormat: 'list' | 'table';
+    indexFormat: 'list' | 'table' | 'htmlTable';
     /**
@@ -71,0 +71,0 @@ * Sets the format of property groups for interfaces.

package.json

 {
   "name": "typedoc-plugin-markdown",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Lines of code

8150

increased by0.18%

Number of low supply chain risk alerts

3

decreased by-25%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Total package byte prevSize

333858

decreased by-0.11%

Number of package files

305

decreased by-0.65%

No dependency changes