typedoc-plugin-markdown - npm Package Compare versions

Comparing version 4.0.0-next.22 to 4.0.0-next.23

dist/plugin/options/config.d.ts

@@ -116,14 +116,2 @@ import { DeclarationOption } from 'typedoc';
  *
- * Example for displaying name only:
- *
- * ```
- * titleTemplate: "{name}"
- * ```
- *
- * Example for displaying kind in backticks:
- *
- * ```
- * titleTemplate: "{name} `{kind}`"
- * ```
- *
  * @category ui
@@ -135,28 +123,4 @@ */
  *
- * This creates a flat structure where all members are displayed at the same level.
+ * This creates a flat structure where all members are displayed at the same heading level.
  *
- * **With groups**
- *
- * ```markdown
- * # SomeModule
- *
- * ## Classes
- *
- * ### ClassA
- *
- * ## Functions
- *
- * ### FunctionA
- *```
- *
- * **Without groups**
- *
- * ```markdown
- * # SomeModule
- *
- * ## ClassA
- *
- * ## FunctionA
- * ```
- *
  * @category ui
@@ -168,16 +132,6 @@ */
  *
- * *Default example:*
+ * Please note that when this option is set to `true` it is not possible to link to other references.
  *
- * > **basicFunction**(someParam): `string`
+ * As a work around the `{\@link}` tag can be be used to manually reference types.
  *
- * *Example inside code block:*
- *
- * ```ts
- * basicFunction(someParam): string
- * ```
- *
- * Note when this option is set to `true` it is not possible to link to other references.
- *
- * As a work around the {\@link} tag can be be used to manually reference types.
- *
  * @category ui
@@ -217,2 +171,4 @@ */
 /**
+ * This determines wheter to display index items either as a simple lists or in a table with a description column exposing the comment summary.
+ *
  * @category ui
@@ -219,0 +175,0 @@ */

dist/plugin/options/config.js

@@ -164,3 +164,3 @@ "use strict";
     type: typedoc_1.ParameterType.String,
-    defaultValue: '{projectName}',
+    defaultValue: 'API',
 };
@@ -170,14 +170,2 @@ /**
  *
- * Example for displaying name only:
- *
- * ```
- * titleTemplate: "{name}"
- * ```
- *
- * Example for displaying kind in backticks:
- *
- * ```
- * titleTemplate: "{name} `{kind}`"
- * ```
- *
  * @category ui
@@ -194,28 +182,4 @@ */
  *
- * This creates a flat structure where all members are displayed at the same level.
+ * This creates a flat structure where all members are displayed at the same heading level.
  *
- * **With groups**
- *
- * ```markdown
- * # SomeModule
- *
- * ## Classes
- *
- * ### ClassA
- *
- * ## Functions
- *
- * ### FunctionA
- *```
- *
- * **Without groups**
- *
- * ```markdown
- * # SomeModule
- *
- * ## ClassA
- *
- * ## FunctionA
- * ```
- *
  * @category ui
@@ -232,16 +196,6 @@ */
  *
- * *Default example:*
+ * Please note that when this option is set to `true` it is not possible to link to other references.
  *
- * > **basicFunction**(someParam): `string`
+ * As a work around the `{\@link}` tag can be be used to manually reference types.
  *
- * *Example inside code block:*
- *
- * ```ts
- * basicFunction(someParam): string
- * ```
- *
- * Note when this option is set to `true` it is not possible to link to other references.
- *
- * As a work around the {\@link} tag can be be used to manually reference types.
- *
  * @category ui
@@ -251,3 +205,3 @@ */
     name: 'useCodeBlocks',
-    help: 'Format signatures and declarations in code blocks.',
+    help: 'Wraps signatures and declarations in code blocks.',
     type: typedoc_1.ParameterType.Boolean,
@@ -290,3 +244,3 @@ defaultValue: false,
     name: 'propertiesFormat',
-    help: 'Specify the render style of properties groups for interfaces and classes.',
+    help: 'Specify the render style of property groups for interfaces and classes.',
     type: typedoc_1.ParameterType.Map,
@@ -301,3 +255,3 @@ map: custom_maps_1.FormatStyle,
     name: 'enumMembersFormat',
-    help: 'Specify the render style of Enum members.',
+    help: 'Specify the render style of enumuration members.',
     type: typedoc_1.ParameterType.Map,
@@ -318,2 +272,4 @@ map: custom_maps_1.FormatStyle,
 /**
+ * This determines wheter to display index items either as a simple lists or in a table with a description column exposing the comment summary.
+ *
  * @category ui
@@ -323,3 +279,3 @@ */
     name: 'indexFormat',
-    help: 'Render indexes either as a simple list or a table with a description.',
+    help: 'Specify the render format for index items.',
     type: typedoc_1.ParameterType.Map,
@@ -326,0 +282,0 @@ map: custom_maps_1.FormatStyle,

dist/plugin/renderer.d.ts

@@ -17,4 +17,1 @@ /**
 export declare function renderMarkdown(project: ProjectReflection, outputDirectory: string): Promise<void>;
-export declare function writeFileSync(fileName: string, data: string): void;
-export declare function normalizePath(path: string): string;
-export declare function nicePath(absPath: string): string;

dist/plugin/renderer.js

@@ -30,3 +30,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.nicePath = exports.normalizePath = exports.writeFileSync = exports.renderMarkdown = exports.generateMarkdown = void 0;
+exports.renderMarkdown = exports.generateMarkdown = void 0;
 const fs = __importStar(require("fs"));
@@ -130,7 +130,5 @@ const path = __importStar(require("path"));
 }
-exports.writeFileSync = writeFileSync;
 function normalizePath(path) {
     return path.replace(/\\/g, '/');
 }
-exports.normalizePath = normalizePath;
 function nicePath(absPath) {
@@ -145,2 +143,1 @@ if (!path.isAbsolute(absPath))
 }
-exports.nicePath = nicePath;

dist/support/elements.js

@@ -26,3 +26,3 @@ "use strict";
 exports.unorderedList = unorderedList;
-const horizontalRule = () => '\n\n***';
+const horizontalRule = () => '\n\n***\n\n';
 exports.horizontalRule = horizontalRule;
@@ -29,0 +29,0 @@ const codeBlock = (content) => '```ts\n' + (0, utils_1.unEscapeChars)(content) + '\n```';

dist/theme/helpers.d.ts

@@ -11,3 +11,3 @@ /**
 export declare function hasIndex(reflection: DeclarationReflection | ProjectReflection): boolean | undefined;
-export declare function hasTOC(reflection: DeclarationReflection | ProjectReflection): boolean | undefined;
+export declare function isAbsoluteIndex(reflection: DeclarationReflection | ProjectReflection): boolean | undefined;
 export declare function isGroupKind(reflection: DeclarationReflection | SignatureReflection): boolean;
@@ -14,0 +14,0 @@ export declare function getModifier(reflection: DeclarationReflection): "private" | "readonly" | "static" | "abstract" | "get" | "set" | null;

dist/theme/helpers.js

@@ -9,3 +9,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getIndexFileName = exports.getSignatureParameters = exports.flattenDeclarations = exports.declarationHasParent = exports.getMemberTitle = exports.KEYWORD_MAP = exports.getModifier = exports.isGroupKind = exports.hasTOC = exports.hasIndex = exports.getProjectDisplayName = exports.getDeclarationType = void 0;
+exports.getIndexFileName = exports.getSignatureParameters = exports.flattenDeclarations = exports.declarationHasParent = exports.getMemberTitle = exports.KEYWORD_MAP = exports.getModifier = exports.isGroupKind = exports.isAbsoluteIndex = exports.hasIndex = exports.getProjectDisplayName = exports.getDeclarationType = void 0;
 const typedoc_1 = require("typedoc");
@@ -39,12 +39,7 @@ const elements_1 = require("../support/elements");
 exports.hasIndex = hasIndex;
-function hasTOC(reflection) {
+function isAbsoluteIndex(reflection) {
     var _a;
-    return (reflection.kindOf([
-        typedoc_1.ReflectionKind.Project,
-        typedoc_1.ReflectionKind.Module,
-        typedoc_1.ReflectionKind.Namespace,
-    ]) &&
-        ((_a = reflection.groups) === null || _a === void 0 ? void 0 : _a.some((group) => !group.allChildrenHaveOwnDocument())));
+    return (_a = reflection.groups) === null || _a === void 0 ? void 0 : _a.every((group) => group.allChildrenHaveOwnDocument());
 }
-exports.hasTOC = hasTOC;
+exports.isAbsoluteIndex = isAbsoluteIndex;
 function isGroupKind(reflection) {
@@ -51,0 +46,0 @@ return reflection.kindOf([

dist/theme/resources/partials/breadcrumbs.js

@@ -17,3 +17,3 @@ "use strict";
     }
-    md.push((0, elements_1.link)('API', context.relativeURL(page.project.url)));
+    md.push((0, elements_1.link)(context.options.getValue('indexPageTitle'), context.relativeURL(page.project.url)));
     const breadcrumb = (model) => {
@@ -20,0 +20,0 @@ var _a;

dist/theme/resources/partials/footer.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.footer = void 0;
+const elements_1 = require("../../../support/elements");
 /**
@@ -9,3 +10,3 @@ * @category Partials
     if (!context.options.getValue('hideGenerator')) {
-        return `***\nGenerated using [typedoc-plugin-markdown](https://www.npmjs.com/package/typedoc-plugin-markdown) and [TypeDoc](https://typedoc.org/)`;
+        return `${(0, elements_1.horizontalRule)()}Generated using [typedoc-plugin-markdown](https://www.npmjs.com/package/typedoc-plugin-markdown) and [TypeDoc](https://typedoc.org/)`;
     }
@@ -12,0 +13,0 @@ return '';

dist/theme/resources/partials/header.js

@@ -40,3 +40,3 @@ "use strict";
     if (hasReadme || !hasBreadcrumbs) {
-        md.push((0, elements_1.link)('API', hasReadme
+        md.push((0, elements_1.link)(context.options.getValue('indexPageTitle'), hasReadme
             ? context.relativeURL(indexFileName)
@@ -43,0 +43,0 @@ : context.relativeURL(entryFileName)));

dist/theme/resources/partials/index.page.js

@@ -28,3 +28,2 @@ "use strict";
 const path = __importStar(require("path"));
-const typedoc_1 = require("typedoc");
 const elements_1 = require("../../../support/elements");
@@ -37,6 +36,6 @@ const utils_1 = require("../../../support/utils");
 function pageIndex(context, page, headingLevel) {
-    var _a, _b;
+    var _a;
     const md = [];
     if (!page.model.groups) {
-        md.push((0, elements_1.heading)(headingLevel, 'Packages'));
+        md.push((0, elements_1.heading)(headingLevel, 'Index'));
         const packagesList = (_a = page.model.children) === null || _a === void 0 ? void 0 : _a.map((projectPackage) => {
@@ -50,15 +49,9 @@ return `- [${(0, utils_1.escapeChars)(projectPackage.name)}](${context.relativeURL(Boolean(projectPackage.readme)
     }
-    const isModules = (_b = page.model.children) === null || _b === void 0 ? void 0 : _b.every((child) => child.kindOf(typedoc_1.ReflectionKind.Module));
     if ((0, helpers_1.hasIndex)(page.model)) {
-        if (!isModules) {
-            md.push((0, elements_1.heading)(headingLevel, 'Exports'));
-        }
-        md.push(context.reflectionIndex(page.model, false, isModules ? headingLevel : headingLevel + 1));
+        md.push((0, elements_1.heading)(headingLevel, 'Index'));
+        md.push(context.reflectionIndex(page.model, false, headingLevel + 1));
         return md.join('\n\n');
     }
-    if (!context.options.getValue('hideInPageTOC') && (0, helpers_1.hasTOC)(page.model)) {
-        md.push(context.reflectionIndex(page.model, true, headingLevel));
-    }
     return md.join('\n\n');
 }
 exports.pageIndex = pageIndex;

dist/theme/resources/partials/member.reflection.js

@@ -41,9 +41,8 @@ "use strict";
     if ((0, helpers_1.hasIndex)(reflection)) {
-        md.push((0, elements_1.heading)(headingLevel, 'Index'));
-        md.push(context.reflectionIndex(reflection, false, headingLevel + 1));
+        const isAbsolute = (0, helpers_1.isAbsoluteIndex)(reflection);
+        if (isAbsolute) {
+            md.push((0, elements_1.heading)(headingLevel, 'Index'));
+        }
+        md.push(context.reflectionIndex(reflection, false, isAbsolute ? headingLevel + 1 : headingLevel));
     }
-    if (!context.options.getValue('hideInPageTOC') && (0, helpers_1.hasTOC)(reflection)) {
-        md.push((0, elements_1.heading)(headingLevel, 'Table of contents'));
-        md.push(context.reflectionIndex(reflection, true, headingLevel + 1));
-    }
     md.push(context.members(reflection, headingLevel));
@@ -50,0 +49,0 @@ return md.join('\n\n');

dist/theme/resources/partials/page.title.js

@@ -14,3 +14,3 @@ "use strict";
     if (((_a = page.model) === null || _a === void 0 ? void 0 : _a.url) === page.project.url) {
-        return 'API';
+        return context.options.getValue('indexPageTitle');
     }
@@ -17,0 +17,0 @@ return titleTemplate

dist/theme/resources/templates/project.js

@@ -5,3 +5,2 @@ "use strict";
 const elements_1 = require("../../../support/elements");
-const helpers_1 = require("../../helpers");
 /**
@@ -25,5 +24,2 @@ * @category Templates
     md.push(context.pageIndex(page, 2));
-    if (!context.options.getValue('hideInPageTOC') && (0, helpers_1.hasTOC)(page.model)) {
-        md.push(context.reflectionIndex(page.model, true, 2));
-    }
     md.push(context.members(page.model, 2));
@@ -30,0 +26,0 @@ md.push(context.footer());

dist/theme/theme.d.ts

@@ -1,2 +0,2 @@
-import { DeclarationReflection, ProjectReflection, Reflection, ReflectionKind, RenderTemplate, Renderer, Theme } from 'typedoc';
+import { DeclarationReflection, PageEvent, ProjectReflection, Reflection, ReflectionKind, RenderTemplate, Renderer, Theme } from 'typedoc';
 import { MarkdownPageEvent } from '../plugin/events';
@@ -33,2 +33,4 @@ import { UrlMapping } from '../plugin/url-mapping';
     getNavigation(project: ProjectReflection): NavigationItem[];
+    hasToc(page: PageEvent): boolean | undefined;
+    insertToc(page: PageEvent, contents: string): string;
     /**
@@ -35,0 +37,0 @@ * Returns the template mapping for a given reflection kind

dist/theme/theme.js

@@ -49,3 +49,4 @@ "use strict";
     render(page, template) {
-        return template(page);
+        const contents = template(page);
+        return this.hasToc(page) ? this.insertToc(page, contents) : contents;
     }
@@ -58,2 +59,46 @@ getUrls(project) {
     }
+    hasToc(page) {
+        var _a;
+        if (this.application.options.getValue('hideInPageTOC')) {
+            return false;
+        }
+        const reflection = page.model;
+        return (reflection.kindOf([
+            typedoc_1.ReflectionKind.Project,
+            typedoc_1.ReflectionKind.Module,
+            typedoc_1.ReflectionKind.Namespace,
+            typedoc_1.ReflectionKind.Enum,
+            typedoc_1.ReflectionKind.Class,
+            typedoc_1.ReflectionKind.Interface,
+        ]) &&
+            ((_a = reflection.groups) === null || _a === void 0 ? void 0 : _a.some((group) => !group.allChildrenHaveOwnDocument())));
+    }
+    insertToc(page, contents) {
+        var _a;
+        const regXHeader = /(?<flag>#{2,6})\s+(?<content>.+)/g;
+        const anchors = [];
+        const toc = (_a = Array.from(contents === null || contents === void 0 ? void 0 : contents.matchAll(regXHeader))) === null || _a === void 0 ? void 0 : _a.map(({ groups: { flag, content } }) => {
+            return {
+                heading: flag.length,
+                content,
+            };
+        }).map((item) => {
+            var _a;
+            anchors.push(item.content);
+            const count = (_a = anchors === null || anchors === void 0 ? void 0 : anchors.filter((id) => id === item.content)) === null || _a === void 0 ? void 0 : _a.length;
+            return { ...item, count };
+        }).filter((item) => item.heading < 4).map((item) => {
+            const spaces = Array.from({ length: item.heading })
+                .map((_, i) => (i > 1 ? '  ' : ''))
+                .join('');
+            const urlParts = page === null || page === void 0 ? void 0 : page.url.split('/');
+            return `${spaces}- [${item.content}](${urlParts[urlParts.length - 1]}#${(0, utils_1.slugify)(item.content).toLowerCase()}${item.count > 1 ? `-${item.count - 1}` : ''})`;
+        }).join('\n');
+        const contentToLines = contents === null || contents === void 0 ? void 0 : contents.split('\n');
+        const firstHeadingIndex = contentToLines === null || contentToLines === void 0 ? void 0 : contentToLines.findIndex((line) => line.startsWith('##'));
+        if (firstHeadingIndex && firstHeadingIndex > 0) {
+            contentToLines === null || contentToLines === void 0 ? void 0 : contentToLines.splice(firstHeadingIndex, 0, `\n\n## Contents\n\n${toc}\n\n`);
+        }
+        return contentToLines === null || contentToLines === void 0 ? void 0 : contentToLines.join('\n');
+    }
     /**
@@ -60,0 +105,0 @@ * Returns the template mapping for a given reflection kind

package.json

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

No alert changes

Improved metrics

Total package byte prevSize

197557

increased by0.4%

Worsened metrics

Lines of code

4673

decreased by-1.33%

No dependency changes