From 48fbe691b58bdea522da1e9ec43eccc0118b10fc Mon Sep 17 00:00:00 2001 From: tgreyuk Date: Mon, 27 May 2024 10:34:37 +0100 Subject: [PATCH] fix(core): further typedoc beta fixes --- devtools/packages/fixtures/typedoc.cjs | 5 + devtools/packages/helpers/constants.ts | 2 +- .../prebuild-options/tasks/generate-docs.ts | 6 +- .../prebuild-options/tasks/generate-models.ts | 53 +- .../pages/api-docs/Class.MarkdownPageEvent.md | 43 +- .../api-docs/Class.MarkdownRendererEvent.md | 24 +- docs/pages/api-docs/Class.MarkdownTheme.md | 36 +- .../api-docs/Class.MarkdownThemeContext.md | 538 ++++++++++++++---- .../api-docs/Interface.MarkdownApplication.md | 12 +- .../api-docs/Interface.MarkdownRenderer.md | 30 +- .../Interface.MarkdownRendererHooks.md | 20 +- .../api-docs/Interface.NavigationItem.md | 16 +- .../api-docs/Interface.PackageMetaData.md | 8 +- .../pages/api-docs/Interface.PluginOptions.md | 243 ++++++-- docs/pages/api-docs/Interface.UrlMapping.md | 12 +- docs/pages/api-docs/index.md | 6 +- docs/pages/docs/CHANGELOG.md | 126 ---- docs/pages/docs/_meta.js | 4 +- .../4.0.mdx} | 26 +- docs/pages/docs/changelog/4.1.mdx | 31 + docs/pages/docs/changelog/_meta.js | 4 + docs/pages/docs/internationalization.mdx | 3 + docs/pages/docs/options.mdx | 6 +- docs/pages/docs/options/display-options.mdx | 39 +- docs/pages/docs/options/file-options.mdx | 22 +- docs/pages/docs/options/utility-options.mdx | 29 +- docs/theme.config.jsx | 2 +- package-lock.json | 28 +- package.json | 2 +- .../docusaurus-plugin-typedoc/package.json | 2 +- .../__snapshots__/docusaurus.spec.ts.snap | 2 +- .../.docs/plugins/typedoc-symbol-resolver.mjs | 18 - .../.docs/typedoc.html.json | 80 +++ .../.docs/typedoc.json | 12 +- .../.scripts/prebuild-kinds.ts | 90 --- .../.scripts/prebuild-resources.ts | 38 +- packages/typedoc-plugin-markdown/package.json | 2 +- .../src/app/application.ts | 30 +- .../src/app/events/markdown-page-event.ts | 11 +- .../app/internationalization/locales/en.ts | 16 + .../app/internationalization/locales/ko.ts | 18 + .../translatable-types.ts | 18 + .../app/internationalization/translatable.ts | 22 + .../src/app/renderer/overrides.ts | 6 +- .../src/app/translatable.ts | 73 --- .../src/defs/typedoc.d.ts | 30 +- packages/typedoc-plugin-markdown/src/index.ts | 25 +- .../src/options/declarations.ts | 98 ++-- .../src/options/option-maps.ts | 23 +- .../src/options/option-types.ts | 34 +- .../typedoc-plugin-markdown/src/public-api.ts | 2 +- .../src/theme/core/navigation-builder.ts | 2 +- .../src/theme/core/url-builder.ts | 21 +- .../src/theme/markdown-theme.ts | 19 - .../src/theme/markdown-themecontext.ts | 12 +- .../resources/helpers/get-comment-parts.ts | 70 +++ .../helpers/get-group-index-table.ts | 4 +- .../resources/helpers/get-project-name.ts | 16 + .../get-reflection-flags.ts} | 23 +- .../resources/helpers/use-table.format.ts | 24 + .../src/theme/resources/index.ts | 30 +- .../resources/partials/comments.comment.ts | 2 +- .../resources/partials/container.groups.ts | 24 +- .../resources/partials/member.accessor.ts | 2 +- .../resources/partials/member.declaration.ts | 15 +- .../resources/partials/member.documents.ts | 14 +- .../partials/member.enumMembersTable.ts | 4 +- .../partials/member.memberWithGroups.ts | 2 +- .../partials/member.parametersTable.ts | 4 +- .../partials/member.propertiesTable.ts | 38 +- .../resources/partials/member.signature.ts | 13 +- .../resources/partials/member.sources.ts | 2 +- .../partials/member.typeDeclarationTable.ts | 10 +- .../partials/member.typeParametersTable.ts | 9 +- .../resources/partials/page.breadcrumbs.ts | 12 +- .../theme/resources/partials/page.footer.ts | 3 +- .../theme/resources/partials/page.header.ts | 16 +- .../resources/partials/page.packagesIndex.ts | 4 +- .../resources/partials/page.pageTitle.ts | 20 +- .../src/theme/resources/templates/project.ts | 12 +- .../test/fixtures/config.ts | 38 +- .../test/fixtures/src/comments/index.ts | 13 +- .../test/fixtures/typedoc.text-locales.cjs | 19 + ...-options.cjs => typedoc.text-mappings.cjs} | 17 +- .../specs/__snapshots__/comments.spec.ts.snap | 131 ++++- .../__snapshots__/navigation.spec.ts.snap | 116 +++- .../objects-and-params.spec.ts.snap | 4 +- .../specs/__snapshots__/readme.spec.ts.snap | 6 +- .../reflection.class.spec.ts.snap | 26 +- .../reflection.function.spec.ts.snap | 8 +- .../reflection.interface.spec.ts.snap | 12 +- .../specs/__snapshots__/text.spec.ts.snap | 67 ++- .../specs/__snapshots__/urls.spec.ts.snap | 28 + .../test/specs/comments.spec.ts | 4 + .../test/specs/text.spec.ts | 8 +- 95 files changed, 1902 insertions(+), 1048 deletions(-) delete mode 100644 docs/pages/docs/CHANGELOG.md rename docs/pages/docs/{migration-guide.mdx => changelog/4.0.mdx} (85%) create mode 100644 docs/pages/docs/changelog/4.1.mdx create mode 100644 docs/pages/docs/changelog/_meta.js create mode 100644 docs/pages/docs/internationalization.mdx delete mode 100644 packages/typedoc-plugin-markdown/.docs/plugins/typedoc-symbol-resolver.mjs create mode 100644 packages/typedoc-plugin-markdown/.docs/typedoc.html.json delete mode 100644 packages/typedoc-plugin-markdown/.scripts/prebuild-kinds.ts create mode 100644 packages/typedoc-plugin-markdown/src/app/internationalization/locales/en.ts create mode 100644 packages/typedoc-plugin-markdown/src/app/internationalization/locales/ko.ts create mode 100644 packages/typedoc-plugin-markdown/src/app/internationalization/translatable-types.ts create mode 100644 packages/typedoc-plugin-markdown/src/app/internationalization/translatable.ts delete mode 100644 packages/typedoc-plugin-markdown/src/app/translatable.ts create mode 100644 packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-comment-parts.ts create mode 100644 packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-project-name.ts rename packages/typedoc-plugin-markdown/src/theme/resources/{partials/member.reflectionFlags.ts => helpers/get-reflection-flags.ts} (53%) create mode 100644 packages/typedoc-plugin-markdown/src/theme/resources/helpers/use-table.format.ts create mode 100644 packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-locales.cjs rename packages/typedoc-plugin-markdown/test/fixtures/{typedoc.text-options.cjs => typedoc.text-mappings.cjs} (59%) diff --git a/devtools/packages/fixtures/typedoc.cjs b/devtools/packages/fixtures/typedoc.cjs index 3b9925aab..a01312618 100644 --- a/devtools/packages/fixtures/typedoc.cjs +++ b/devtools/packages/fixtures/typedoc.cjs @@ -15,4 +15,9 @@ module.exports = { navigation: { includeGroups: true, }, + locales: { + en: { + theme_defined_in: 'Source', + }, + }, }; diff --git a/devtools/packages/helpers/constants.ts b/devtools/packages/helpers/constants.ts index 8e42ba188..bf48a5a77 100644 --- a/devtools/packages/helpers/constants.ts +++ b/devtools/packages/helpers/constants.ts @@ -6,7 +6,7 @@ export const PRESETS_PATH = `${process.cwd()}/src/options/presets.ts`; export const DOCS_CONFIG: Record = { ['typedoc-plugin-markdown']: { declarationsPath: `${process.cwd()}/src/options/declarations.ts`, - translatablePath: `${process.cwd()}/src/app/translatable.ts`, + translatablePath: `${process.cwd()}/src/app/internationalization/locales/en.ts`, optionsPath: '/docs', docsPath: '/docs', declarations: true, diff --git a/devtools/packages/prebuild-options/tasks/generate-docs.ts b/devtools/packages/prebuild-options/tasks/generate-docs.ts index e576165c3..90da46334 100644 --- a/devtools/packages/prebuild-options/tasks/generate-docs.ts +++ b/devtools/packages/prebuild-options/tasks/generate-docs.ts @@ -160,7 +160,8 @@ ${presetsJson} if ( option.type !== ParameterType.Flags && option.type !== ParameterType.Array && - option.type !== ParameterType.Mixed + option.type !== ParameterType.Mixed && + option.type !== ParameterType.Object ) { meta.push(`Defaults to \`${getDefaultValue(option)}\`.`); } @@ -306,6 +307,9 @@ function getDefaultValue(option) { 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/devtools/packages/prebuild-options/tasks/generate-models.ts b/devtools/packages/prebuild-options/tasks/generate-models.ts index 998263387..f1f32385f 100644 --- a/devtools/packages/prebuild-options/tasks/generate-models.ts +++ b/devtools/packages/prebuild-options/tasks/generate-models.ts @@ -78,9 +78,12 @@ async function writeOptionsTypes( option.type === ParameterType.Mixed && option.defaultValue, ); - const optionsOutput = ` - // THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY. + const optionsOutput: string[] = [ + `// THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY. +`, + ]; + optionsOutput.push(` /** * Describes the options declared by the plugin. * @@ -117,20 +120,41 @@ ${name}: ${getType(name, option, true)};`, `; }) .join('\n')} - `; + `); const optionsModelFile = path.join( path.dirname(docsConfig.declarationsPath as string), 'option-types.ts', ); - const formatted = await prettier.format(optionsOutput, { + const formatted = await prettier.format(optionsOutput.join('\n\n'), { parser: 'typescript', singleQuote: true, trailingComma: 'all', }); fs.writeFileSync(optionsModelFile, formatted); + + if (docsConfig.translatablePath) { + const translatableOutput: string[] = [ + '// THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.', + ]; + const { translatable } = await import(docsConfig.translatablePath); + translatableOutput.push( + ` +export interface TranslatableStrings ${getTranslationsInterface(translatable)}`, + ); + const formatted = await prettier.format(translatableOutput.join('\n\n'), { + parser: 'typescript', + singleQuote: true, + trailingComma: 'all', + }); + const translatableModelFile = path.join( + path.dirname(docsConfig.translatablePath as string), + '../translatable-types.ts', + ); + fs.writeFileSync(translatableModelFile, formatted); + } } function getTranslations(inputObject: { [key: string]: string }) { @@ -142,6 +166,14 @@ function getTranslations(inputObject: { [key: string]: string }) { return JSON.stringify(output).replace(/"/g, ''); } +function getTranslationsInterface(inputObject: { [key: string]: string }) { + const output: { [key: string]: string } = {}; + for (const [key] of Object.entries(inputObject)) { + output[key] = 'string'; + } + return JSON.stringify(output).replace(/"/g, ''); +} + function getComments(name: string) { if (name === 'textContentMappings') { return 'Describes the keys available to replace static text.'; @@ -208,9 +240,22 @@ function getType( .map((value) => `"${value}"`) .join(' | ')}`; } + if (option.type === ParameterType.Object) { + const outType = `{${Object.keys(option.defaultValue as any) + .map((key) => `'${key}': ${getObjectType(name)};`) + .join('')}}`; + return isInterface ? outType : `ManuallyValidatedOption<${outType}>`; + } return 'any'; } +function getObjectType(name: string) { + if (name === 'reflectionFormats') { + return "'list'|'table'|'htmlTable'"; + } + return 'string'; +} + function capitalize(str: string) { return str.charAt(0).toUpperCase() + str.slice(1); } diff --git a/docs/pages/api-docs/Class.MarkdownPageEvent.md b/docs/pages/api-docs/Class.MarkdownPageEvent.md index 553fa0bcf..66d0eb352 100644 --- a/docs/pages/api-docs/Class.MarkdownPageEvent.md +++ b/docs/pages/api-docs/Class.MarkdownPageEvent.md @@ -20,41 +20,52 @@ export function load(app: MarkdownApplication) { ### project -> **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) +```ts +project: ProjectReflection; +``` -The project the renderer is currently processing. +The [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) instance the renderer is currently processing. *** ### model -> `readonly` **model**: `Model` +```ts +readonly model: Model; +``` -The model that should be rendered on this page. +The model that that is being rendered on this page. +Either a [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) or [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html). *** ### url -> **url**: `string` +```ts +url: string; +``` -The url this page will be located at. +The url `string` of the page. *** ### filename -> **filename**: `string` +```ts +filename: string; +``` -The filename the page will be written to. +The complete `string` filename where the file will be written.. *** ### contents? -> `optional` **contents**: `string` +```ts +optional contents: string; +``` -The final markdown content of this page. +The final markdown `string` content of the page. Should be rendered by layout templates and can be modified by plugins. @@ -62,7 +73,9 @@ Should be rendered by layout templates and can be modified by plugins. ### frontmatter? -> `optional` **frontmatter**: `Record`\<`string`, `any`\> +```ts +optional frontmatter: Record; +``` The frontmatter of this page represented as a key value object. This property can be utilised by other plugins. @@ -70,7 +83,9 @@ The frontmatter of this page represented as a key value object. This property ca ### BEGIN -> `static` `readonly` **BEGIN**: `"beginPage"` = `'beginPage'` +```ts +static readonly BEGIN: "beginPage" = 'beginPage'; +``` Triggered before a document will be rendered. @@ -78,6 +93,8 @@ Triggered before a document will be rendered. ### END -> `static` `readonly` **END**: `"endPage"` = `'endPage'` +```ts +static readonly END: "endPage" = 'endPage'; +``` Triggered after a document has been rendered, just before it is written to disc. diff --git a/docs/pages/api-docs/Class.MarkdownRendererEvent.md b/docs/pages/api-docs/Class.MarkdownRendererEvent.md index be21c5003..0ffa47528 100644 --- a/docs/pages/api-docs/Class.MarkdownRendererEvent.md +++ b/docs/pages/api-docs/Class.MarkdownRendererEvent.md @@ -18,7 +18,9 @@ app.renderer.on(MarkdownRendererEvent.BEGIN, (event) => { ### project -> `readonly` **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) +```ts +readonly project: ProjectReflection; +``` The project the renderer is currently processing. @@ -26,7 +28,9 @@ The project the renderer is currently processing. ### outputDirectory -> `readonly` **outputDirectory**: `string` +```ts +readonly outputDirectory: string; +``` The path of the directory the documentation should be written to. @@ -34,7 +38,9 @@ The path of the directory the documentation should be written to. ### urls? -> `optional` **urls**: [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[] +```ts +optional urls: UrlMapping[]; +``` A list of all pages that should be generated. @@ -42,7 +48,9 @@ A list of all pages that should be generated. ### navigation? -> `optional` **navigation**: [`NavigationItem`](/api-docs/Interface.NavigationItem.md)[] +```ts +optional navigation: NavigationItem[]; +``` The navigation structure of the project that can be utilised by plugins. @@ -50,7 +58,9 @@ The navigation structure of the project that can be utilised by plugins. ### BEGIN -> `static` `readonly` **BEGIN**: `"beginRender"` = `'beginRender'` +```ts +static readonly BEGIN: "beginRender" = 'beginRender'; +``` Triggered before the renderer starts rendering a project. @@ -58,6 +68,8 @@ Triggered before the renderer starts rendering a project. ### END -> `static` `readonly` **END**: `"endRender"` = `'endRender'` +```ts +static readonly END: "endRender" = 'endRender'; +``` Triggered after the renderer has written all documents. diff --git a/docs/pages/api-docs/Class.MarkdownTheme.md b/docs/pages/api-docs/Class.MarkdownTheme.md index 8855ff51b..b6764e07f 100644 --- a/docs/pages/api-docs/Class.MarkdownTheme.md +++ b/docs/pages/api-docs/Class.MarkdownTheme.md @@ -24,11 +24,37 @@ class MyMarkdownTheme extends MarkdownTheme { - [`Theme`](https://typedoc.org/api/classes/Theme.html) +## Constructors + +### new MarkdownTheme() + +```ts +new MarkdownTheme(owner): MarkdownTheme +``` + +Create new Component instance. + +#### Parameters + +| Parameter | Type | +| :------ | :------ | +| `owner` | [`Renderer`](https://typedoc.org/api/classes/Renderer.html) | + +#### Returns + +[`MarkdownTheme`](/api-docs/Class.MarkdownTheme.md) + +#### Inherited from + +`Theme.constructor` + ## Methods ### getRenderContext() -> **getRenderContext**(`page`): [`MarkdownThemeContext`](/api-docs/Class.MarkdownThemeContext.md) +```ts +getRenderContext(page): MarkdownThemeContext +``` Creates a new instance of the current theme context. @@ -48,7 +74,9 @@ This method can be overridden to provide an alternative theme context. ### getUrls() -> **getUrls**(`project`): [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[] +```ts +getUrls(project): UrlMapping[] +``` Maps the models of the given project to the desired output files. @@ -72,7 +100,9 @@ This method can be overriden to provide an alternative url structure. ### getNavigation() -> **getNavigation**(`project`): [`NavigationItem`](/api-docs/Interface.NavigationItem.md)[] +```ts +getNavigation(project): NavigationItem[] +``` Map the models of the given project to a navigation structure. diff --git a/docs/pages/api-docs/Class.MarkdownThemeContext.md b/docs/pages/api-docs/Class.MarkdownThemeContext.md index 747790ce5..99302f22f 100644 --- a/docs/pages/api-docs/Class.MarkdownThemeContext.md +++ b/docs/pages/api-docs/Class.MarkdownThemeContext.md @@ -4,7 +4,7 @@ The theme context class that is provided as context on the rendering of every pa It is heavily influenced by the equivalent [DefaultThemeRenderContext](https://typedoc.org/api/classes/DefaultThemeRenderContext.html) from the default theme. -This class can be used to customize the theme output by extending the class and overriding the [templates](#templates), [partials](#partials) and [helpers](#helpers). +This class can be used to customize the theme output by extending the class and overriding the templates, partials and helpers. ## Usage @@ -20,7 +20,12 @@ class MyMarkdownTheme extends MarkdownTheme { ### new MarkdownThemeContext() -> **new MarkdownThemeContext**(`theme`, `page`, `options`): [`MarkdownThemeContext`](/api-docs/Class.MarkdownThemeContext.md) +```ts +new MarkdownThemeContext( + theme, + page, + options): MarkdownThemeContext +``` #### Parameters @@ -40,19 +45,25 @@ Properties are passed into the constructor and are used to provide context to th ### internationalization -> **internationalization**: `Internationalization` +```ts +internationalization: Internationalization; +``` *** ### i18n -> **i18n**: `TranslationProxy` +```ts +i18n: TranslationProxy; +``` *** ### page -> `readonly` **page**: [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\> +```ts +readonly page: MarkdownPageEvent; +``` The current page event. @@ -60,7 +71,9 @@ The current page event. ### options -> `readonly` **options**: [`Options`](https://typedoc.org/api/classes/Configuration.Options.html) +```ts +readonly options: Options; +``` The options provided to the application. @@ -70,7 +83,9 @@ General context aware helper methods not bound to any specific models that can b ### getPackageMetaData() -> **getPackageMetaData**(`packageName`): [`PackageMetaData`](/api-docs/Interface.PackageMetaData.md) +```ts +getPackageMetaData(packageName): PackageMetaData +``` Returns the package meta data for a given package name when entrypointStrategy is set to `packages`. @@ -88,7 +103,9 @@ Returns the package meta data for a given package name when entrypointStrategy i ### getRelativeUrl() -> **getRelativeUrl**(`url`, `ignorePublicPath`): `string` +```ts +getRelativeUrl(url, ignorePublicPath): string +``` Returns the relative URL (from the current page context url). @@ -96,10 +113,10 @@ If public path is set, it will be used as the base URL. #### Parameters -| Parameter | Type | Default Value | Description | -| :------ | :------ | :------ | :------ | -| `url` | `string` | `undefined` | The URL to make relative. | -| `ignorePublicPath` | `boolean` | `false` | Whether to ignore the public path. | +| Parameter | Type | Description | +| :------ | :------ | :------ | +| `url` | `string` | The URL to make relative. | +| `ignorePublicPath` | `boolean` | Whether to ignore the public path. | #### Returns @@ -111,7 +128,14 @@ Theme resources are the main building blocks for the theme context. They are spl ### templates -> **templates**: `object` +```ts +templates: { + document: (page) => string; + project: (page) => string; + readme: (page) => string; + reflection: (page) => string; +}; +``` Then `templates` namespace holds the main templates for the theme and are mapped to single pages and configured in the MarkdownTheme. @@ -119,7 +143,9 @@ All templates return a string that is passed back to the renderer. Internally te #### document() -> **document**: (`page`) => `string` +```ts +document: (page) => string; +``` Template that maps to a project document. @@ -135,7 +161,9 @@ Template that maps to a project document. #### project() -> **project**: (`page`) => `string` +```ts +project: (page) => string; +``` Template that maps to the root project reflection. This will be the index page / documentation root page. @@ -151,7 +179,9 @@ Template that maps to the root project reflection. This will be the index page / #### readme() -> **readme**: (`page`) => `string` +```ts +readme: (page) => string; +``` Template that specifically maps to the resolved readme file. This template is not used when 'readme' is set to 'none'. @@ -167,7 +197,9 @@ Template that specifically maps to the resolved readme file. This template is no #### reflection() -> **reflection**: (`page`) => `string` +```ts +reflection: (page) => string; +``` Template that maps to individual reflection models. @@ -185,7 +217,70 @@ Template that maps to individual reflection models. ### partials -> **partials**: `object` +```ts +partials: { + comment: (model, options) => string; + commentParts: (model) => string; + body: (model, options) => string; + categories: (model, options) => string; + groups: (model, options) => string; + members: (model, options) => string; + accessor: (model, options) => string; + constructor: (model, options) => string; + memberContainer: (model, options) => string; + declaration: (model, options) => string; + declarationTitle: (model) => string; + documents: (model, options) => string; + enumMembersTable: (model) => string; + hierarchy: (model, options) => string; + indexSignature: (model) => string; + inheritance: (model, options) => string; + memberTitle: (model) => string; + memberWithGroups: (model, options) => string; + parametersList: (model) => string; + parametersTable: (model) => string; + propertiesTable: (model, options?) => string; + referenceMember: (model) => string; + reflectionIndex: (model, options) => string; + signature: (model, options) => string; + signatureParameters: (model) => string; + signatureReturns: (model, options) => string; + signatureTitle: (model, options?) => string; + signatures: (model, options) => string; + sources: (model, options) => string; + member: (model, options) => string; + typeAndParent: (model) => string; + typeArguments: (model, options?) => string; + typeDeclaration: (model, options) => string; + typeDeclarationList: (model, headingLevel) => string; + typeDeclarationTable: (model) => string; + typeParametersList: (model) => string; + typeParametersTable: (model) => string; + breadcrumbs: () => string; + footer: () => string; + header: () => string; + packagesIndex: (model) => string; + pageTitle: () => string; + arrayType: (model) => string; + conditionalType: (model) => string; + indexAccessType: (model) => string; + inferredType: (model) => string; + intersectionType: (model) => string; + intrinsicType: (model) => string; + literalType: (model) => string; + namedTupleType: (model) => string; + queryType: (model) => string; + referenceType: (model) => string; + declarationType: (model) => string; + functionType: (model, options?) => string; + reflectionType: (model, options?) => string; + someType: (model?) => string; + tupleType: (model) => string; + typeOperatorType: (model) => string; + unionType: (model) => string; + unknownType: (model) => string; +}; +``` The `partials` namespace holds the partials for the theme and are used by templates to map speficic models to page output. @@ -197,17 +292,19 @@ Please note that partials:: Partials are categorised by their use: -- [Page Partials](#page-partials): Partials that render core page elements such as header and breadcrumbs. -- [Container Partials](#container-partials): Partials that are used to render reflection groups and categories. -- [Member Partials](#member-partials): Partials that render specific parts of reflections. -- [Comment Partials](#comment-partials): Partials that render comments. -- [Type Partials](#type-partials): Partials that render specific TypeDoc model types. +- Page Partials: Partials that render core page elements such as header and breadcrumbs. +- Container Partials: Partials that are used to render reflection groups and categories. +- Member Partials: Partials that render specific parts of reflections. +- Comment Partials: Partials that render comments. +- Type Partials: Partials that render specific TypeDoc model types. #### Page Partials ##### breadcrumbs() -> **breadcrumbs**: () => `string` +```ts +breadcrumbs: () => string; +``` ###### Returns @@ -215,7 +312,9 @@ Partials are categorised by their use: ##### footer() -> **footer**: () => `string` +```ts +footer: () => string; +``` ###### Returns @@ -223,7 +322,9 @@ Partials are categorised by their use: ##### header() -> **header**: () => `string` +```ts +header: () => string; +``` ###### Returns @@ -231,7 +332,9 @@ Partials are categorised by their use: ##### packagesIndex() -> **packagesIndex**: (`model`) => `string` +```ts +packagesIndex: (model) => string; +``` ###### Parameters @@ -245,7 +348,9 @@ Partials are categorised by their use: ##### pageTitle() -> **pageTitle**: () => `string` +```ts +pageTitle: () => string; +``` ###### Returns @@ -255,7 +360,9 @@ Partials are categorised by their use: ##### body() -> **body**: (`model`, `options`) => `string` +```ts +body: (model, options) => string; +``` ###### Parameters @@ -271,7 +378,9 @@ Partials are categorised by their use: ##### categories() -> **categories**: (`model`, `options`) => `string` +```ts +categories: (model, options) => string; +``` Renders a collection of reflection categories. @@ -289,7 +398,9 @@ Renders a collection of reflection categories. ##### groups() -> **groups**: (`model`, `options`) => `string` +```ts +groups: (model, options) => string; +``` Renders a collection of reflection groups. @@ -307,7 +418,9 @@ Renders a collection of reflection groups. ##### members() -> **members**: (`model`, `options`) => `string` +```ts +members: (model, options) => string; +``` Renders a collection of members. @@ -327,7 +440,9 @@ Renders a collection of members. ##### accessor() -> **accessor**: (`model`, `options`) => `string` +```ts +accessor: (model, options) => string; +``` Renders an accessor member. @@ -345,7 +460,9 @@ Renders an accessor member. ##### constructor() -> **constructor**: (`model`, `options`) => `string` +```ts +constructor: (model, options) => string; +``` Renders an constructor member. @@ -363,7 +480,9 @@ Renders an constructor member. ##### memberContainer() -> **memberContainer**: (`model`, `options`) => `string` +```ts +memberContainer: (model, options) => string; +``` ###### Parameters @@ -380,7 +499,9 @@ Renders an constructor member. ##### declaration() -> **declaration**: (`model`, `options`) => `string` +```ts +declaration: (model, options) => string; +``` Renders a standard declaration member. @@ -399,7 +520,9 @@ Renders a standard declaration member. ##### declarationTitle() -> **declarationTitle**: (`model`) => `string` +```ts +declarationTitle: (model) => string; +``` ###### Parameters @@ -413,7 +536,9 @@ Renders a standard declaration member. ##### documents() -> **documents**: (`model`, `options`) => `string` +```ts +documents: (model, options) => string; +``` ###### Parameters @@ -429,7 +554,9 @@ Renders a standard declaration member. ##### enumMembersTable() -> **enumMembersTable**: (`model`) => `string` +```ts +enumMembersTable: (model) => string; +``` Renders enum members as a table. @@ -445,7 +572,9 @@ Renders enum members as a table. ##### hierarchy() -> **hierarchy**: (`model`, `options`) => `string` +```ts +hierarchy: (model, options) => string; +``` ###### Parameters @@ -461,7 +590,9 @@ Renders enum members as a table. ##### indexSignature() -> **indexSignature**: (`model`) => `string` +```ts +indexSignature: (model) => string; +``` Renders an index signature block @@ -477,7 +608,9 @@ Renders an index signature block ##### inheritance() -> **inheritance**: (`model`, `options`) => `string` +```ts +inheritance: (model, options) => string; +``` Renders an inheritance section. @@ -495,7 +628,9 @@ Renders an inheritance section. ##### memberTitle() -> **memberTitle**: (`model`) => `string` +```ts +memberTitle: (model) => string; +``` Renders the main member title. @@ -511,7 +646,9 @@ Renders the main member title. ##### memberWithGroups() -> **memberWithGroups**: (`model`, `options`) => `string` +```ts +memberWithGroups: (model, options) => string; +``` Renders a top-level member that contains group and child members such as Classes, Interfaces and Enums. @@ -529,7 +666,9 @@ Renders a top-level member that contains group and child members such as Classes ##### parametersList() -> **parametersList**: (`model`) => `string` +```ts +parametersList: (model) => string; +``` ###### Parameters @@ -543,7 +682,9 @@ Renders a top-level member that contains group and child members such as Classes ##### parametersTable() -> **parametersTable**: (`model`) => `string` +```ts +parametersTable: (model) => string; +``` ###### Parameters @@ -555,9 +696,11 @@ Renders a top-level member that contains group and child members such as Classes `string` -##### declarationsTable() +##### propertiesTable() -> **declarationsTable**: (`model`, `options`?) => `string` +```ts +propertiesTable: (model, options?) => string; +``` Renders a collection of properties in a table. @@ -577,7 +720,9 @@ There is no association list partial for properties as these are handled as a st ##### referenceMember() -> **referenceMember**: (`model`) => `string` +```ts +referenceMember: (model) => string; +``` Renders an reference member. @@ -591,25 +736,11 @@ Renders an reference member. `string` -##### reflectionFlags() - -> **reflectionFlags**: (`model`) => `string` - -Renders the flags of a reflection. - -###### Parameters - -| Parameter | Type | -| :------ | :------ | -| `model` | [`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html) | - -###### Returns - -`string` - ##### reflectionIndex() -> **reflectionIndex**: (`model`, `options`) => `string` +```ts +reflectionIndex: (model, options) => string; +``` ###### Parameters @@ -625,7 +756,9 @@ Renders the flags of a reflection. ##### signature() -> **signature**: (`model`, `options`) => `string` +```ts +signature: (model, options) => string; +``` Renders a signature member. @@ -646,7 +779,9 @@ Renders a signature member. ##### signatureParameters() -> **signatureParameters**: (`model`) => `string` +```ts +signatureParameters: (model) => string; +``` ###### Parameters @@ -660,7 +795,9 @@ Renders a signature member. ##### signatureReturns() -> **signatureReturns**: (`model`, `options`) => `string` +```ts +signatureReturns: (model, options) => string; +``` ###### Parameters @@ -676,7 +813,9 @@ Renders a signature member. ##### signatureTitle() -> **signatureTitle**: (`model`, `options`?) => `string` +```ts +signatureTitle: (model, options?) => string; +``` ###### Parameters @@ -693,7 +832,9 @@ Renders a signature member. ##### signatures() -> **signatures**: (`model`, `options`) => `string` +```ts +signatures: (model, options) => string; +``` Renders a signature collection. @@ -712,7 +853,9 @@ Renders a signature collection. ##### sources() -> **sources**: (`model`, `options`) => `string` +```ts +sources: (model, options) => string; +``` ###### Parameters @@ -728,7 +871,9 @@ Renders a signature collection. ##### member() -> **member**: (`model`, `options`) => `string` +```ts +member: (model, options) => string; +``` ###### Parameters @@ -745,7 +890,9 @@ Renders a signature collection. ##### typeAndParent() -> **typeAndParent**: (`model`) => `string` +```ts +typeAndParent: (model) => string; +``` ###### Parameters @@ -759,7 +906,9 @@ Renders a signature collection. ##### typeArguments() -> **typeArguments**: (`model`, `options`?) => `string` +```ts +typeArguments: (model, options?) => string; +``` ###### Parameters @@ -775,7 +924,9 @@ Renders a signature collection. ##### typeDeclaration() -> **typeDeclaration**: (`model`, `options`) => `string` +```ts +typeDeclaration: (model, options) => string; +``` ###### Parameters @@ -791,7 +942,9 @@ Renders a signature collection. ##### typeDeclarationList() -> **typeDeclarationList**: (`model`, `headingLevel`) => `string` +```ts +typeDeclarationList: (model, headingLevel) => string; +``` ###### Parameters @@ -806,7 +959,9 @@ Renders a signature collection. ##### typeDeclarationTable() -> **typeDeclarationTable**: (`model`) => `string` +```ts +typeDeclarationTable: (model) => string; +``` ###### Parameters @@ -820,7 +975,9 @@ Renders a signature collection. ##### typeParametersList() -> **typeParametersList**: (`model`) => `string` +```ts +typeParametersList: (model) => string; +``` ###### Parameters @@ -834,7 +991,9 @@ Renders a signature collection. ##### typeParametersTable() -> **typeParametersTable**: (`model`) => `string` +```ts +typeParametersTable: (model) => string; +``` ###### Parameters @@ -850,7 +1009,9 @@ Renders a signature collection. ##### comment() -> **comment**: (`model`, `options`) => `string` +```ts +comment: (model, options) => string; +``` ###### Parameters @@ -869,7 +1030,9 @@ Renders a signature collection. ##### commentParts() -> **commentParts**: (`model`) => `string` +```ts +commentParts: (model) => string; +``` ###### Parameters @@ -885,7 +1048,9 @@ Renders a signature collection. ##### arrayType() -> **arrayType**: (`model`) => `string` +```ts +arrayType: (model) => string; +``` ###### Parameters @@ -899,7 +1064,9 @@ Renders a signature collection. ##### conditionalType() -> **conditionalType**: (`model`) => `string` +```ts +conditionalType: (model) => string; +``` ###### Parameters @@ -913,7 +1080,9 @@ Renders a signature collection. ##### indexAccessType() -> **indexAccessType**: (`model`) => `string` +```ts +indexAccessType: (model) => string; +``` ###### Parameters @@ -927,7 +1096,9 @@ Renders a signature collection. ##### inferredType() -> **inferredType**: (`model`) => `string` +```ts +inferredType: (model) => string; +``` ###### Parameters @@ -941,7 +1112,9 @@ Renders a signature collection. ##### intersectionType() -> **intersectionType**: (`model`) => `string` +```ts +intersectionType: (model) => string; +``` ###### Parameters @@ -955,7 +1128,9 @@ Renders a signature collection. ##### intrinsicType() -> **intrinsicType**: (`model`) => `string` +```ts +intrinsicType: (model) => string; +``` ###### Parameters @@ -969,7 +1144,9 @@ Renders a signature collection. ##### literalType() -> **literalType**: (`model`) => `string` +```ts +literalType: (model) => string; +``` ###### Parameters @@ -983,7 +1160,9 @@ Renders a signature collection. ##### namedTupleType() -> **namedTupleType**: (`model`) => `string` +```ts +namedTupleType: (model) => string; +``` ###### Parameters @@ -997,7 +1176,9 @@ Renders a signature collection. ##### queryType() -> **queryType**: (`model`) => `string` +```ts +queryType: (model) => string; +``` ###### Parameters @@ -1011,7 +1192,9 @@ Renders a signature collection. ##### referenceType() -> **referenceType**: (`model`) => `string` +```ts +referenceType: (model) => string; +``` ###### Parameters @@ -1025,7 +1208,9 @@ Renders a signature collection. ##### declarationType() -> **declarationType**: (`model`) => `string` +```ts +declarationType: (model) => string; +``` ###### Parameters @@ -1039,7 +1224,9 @@ Renders a signature collection. ##### functionType() -> **functionType**: (`model`, `options`?) => `string` +```ts +functionType: (model, options?) => string; +``` ###### Parameters @@ -1055,7 +1242,9 @@ Renders a signature collection. ##### reflectionType() -> **reflectionType**: (`model`, `options`?) => `string` +```ts +reflectionType: (model, options?) => string; +``` ###### Parameters @@ -1071,7 +1260,9 @@ Renders a signature collection. ##### someType() -> **someType**: (`model`?) => `string` +```ts +someType: (model?) => string; +``` Takes a generic Type and returns the appropriate partial for it. @@ -1087,7 +1278,9 @@ Takes a generic Type and returns the appropriate partial for it. ##### tupleType() -> **tupleType**: (`model`) => `string` +```ts +tupleType: (model) => string; +``` ###### Parameters @@ -1101,7 +1294,9 @@ Takes a generic Type and returns the appropriate partial for it. ##### typeOperatorType() -> **typeOperatorType**: (`model`) => `string` +```ts +typeOperatorType: (model) => string; +``` ###### Parameters @@ -1115,7 +1310,9 @@ Takes a generic Type and returns the appropriate partial for it. ##### unionType() -> **unionType**: (`model`) => `string` +```ts +unionType: (model) => string; +``` ###### Parameters @@ -1129,7 +1326,9 @@ Takes a generic Type and returns the appropriate partial for it. ##### unknownType() -> **unknownType**: (`model`) => `string` +```ts +unknownType: (model) => string; +``` ###### Parameters @@ -1145,7 +1344,27 @@ Takes a generic Type and returns the appropriate partial for it. ### helpers -> **helpers**: `object` +```ts +helpers: { + getCommentParts: (model) => string; + getDeclarationType: (model) => undefined | SomeType; + getDescriptionForReflection: (model) => null | string; + getFlattenedDeclarations: (model, options?) => DeclarationReflection[]; + getGroupIndexList: (children) => string; + getGroupIndexTable: (children) => string; + getGroupIndex: (group) => any; + getHierarchyType: (model, options?) => string; + getKeyword: (model) => string; + getModifier: (model) => null | string; + getParameterDefaultValue: (model) => string; + getProjectName: (stringWithPlaceholders, page) => string; + getPropertyDefaultValue: (model) => null | string; + getReflectionFlags: (reflection) => string[]; + getReturnType: (model?) => string; + isGroupKind: (model) => boolean; + useTableFormat: (key) => boolean; +}; +``` The `helpers` namespace holds the helpers for the theme and are smaller utility functions that return snippets or text or other data transformations. @@ -1155,9 +1374,27 @@ Please note that partials: - Can reference other helpers but should not reference partials. - Can return strings or other models. +#### getCommentParts() + +```ts +getCommentParts: (model) => string; +``` + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `model` | [`CommentDisplayPart`](https://typedoc.org/api/types/Models.CommentDisplayPart.html)[] | + +##### Returns + +`string` + #### getDeclarationType() -> **getDeclarationType**: (`model`) => `undefined` \| [`SomeType`](https://typedoc.org/api/classes/Models.SomeType.html) +```ts +getDeclarationType: (model) => undefined | SomeType; +``` ##### Parameters @@ -1171,7 +1408,9 @@ Please note that partials: #### getDescriptionForReflection() -> **getDescriptionForReflection**: (`model`) => `null` \| `string` +```ts +getDescriptionForReflection: (model) => null | string; +``` ##### Parameters @@ -1185,7 +1424,9 @@ Please note that partials: #### getFlattenedDeclarations() -> **getFlattenedDeclarations**: (`model`, `options`?) => [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] +```ts +getFlattenedDeclarations: (model, options?) => DeclarationReflection[]; +``` ##### Parameters @@ -1201,7 +1442,9 @@ Please note that partials: #### getGroupIndexList() -> **getGroupIndexList**: (`children`) => `string` +```ts +getGroupIndexList: (children) => string; +``` ##### Parameters @@ -1215,7 +1458,9 @@ Please note that partials: #### getGroupIndexTable() -> **getGroupIndexTable**: (`children`) => `string` +```ts +getGroupIndexTable: (children) => string; +``` ##### Parameters @@ -1229,7 +1474,9 @@ Please note that partials: #### getGroupIndex() -> **getGroupIndex**: (`group`) => `any` +```ts +getGroupIndex: (group) => any; +``` ##### Parameters @@ -1243,7 +1490,9 @@ Please note that partials: #### getHierarchyType() -> **getHierarchyType**: (`model`, `options`?) => `string` +```ts +getHierarchyType: (model, options?) => string; +``` ##### Parameters @@ -1259,7 +1508,9 @@ Please note that partials: #### getKeyword() -> **getKeyword**: (`model`) => `string` +```ts +getKeyword: (model) => string; +``` ##### Parameters @@ -1273,7 +1524,9 @@ Please note that partials: #### getModifier() -> **getModifier**: (`model`) => `null` \| `string` +```ts +getModifier: (model) => null | string; +``` ##### Parameters @@ -1287,7 +1540,9 @@ Please note that partials: #### getParameterDefaultValue() -> **getParameterDefaultValue**: (`model`) => `string` +```ts +getParameterDefaultValue: (model) => string; +``` ##### Parameters @@ -1299,9 +1554,28 @@ Please note that partials: `string` +#### getProjectName() + +```ts +getProjectName: (stringWithPlaceholders, page) => string; +``` + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `stringWithPlaceholders` | `string` | +| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\> | + +##### Returns + +`string` + #### getPropertyDefaultValue() -> **getPropertyDefaultValue**: (`model`) => `null` \| `string` +```ts +getPropertyDefaultValue: (model) => null | string; +``` ##### Parameters @@ -1313,9 +1587,27 @@ Please note that partials: `null` \| `string` +#### getReflectionFlags() + +```ts +getReflectionFlags: (reflection) => string[]; +``` + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `reflection` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) \| [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | + +##### Returns + +`string`[] + #### getReturnType() -> **getReturnType**: (`model`?) => `string` +```ts +getReturnType: (model?) => string; +``` ##### Parameters @@ -1329,7 +1621,9 @@ Please note that partials: #### isGroupKind() -> **isGroupKind**: (`model`) => `boolean` +```ts +isGroupKind: (model) => boolean; +``` ##### Parameters @@ -1340,3 +1634,19 @@ Please note that partials: ##### Returns `boolean` + +#### useTableFormat() + +```ts +useTableFormat: (key) => boolean; +``` + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `key` | `"parameters"` \| `"properties"` \| `"enums"` \| `"typeDeclarations"` | + +##### Returns + +`boolean` diff --git a/docs/pages/api-docs/Interface.MarkdownApplication.md b/docs/pages/api-docs/Interface.MarkdownApplication.md index 3f324c939..5cdae7e1b 100644 --- a/docs/pages/api-docs/Interface.MarkdownApplication.md +++ b/docs/pages/api-docs/Interface.MarkdownApplication.md @@ -1,13 +1,11 @@ # MarkdownApplication -An extended typing of TypeDoc's Application instance. - -This is essentially a copy of the main class with the `renderer` property overridden to the custom [MarkdownRenderer](/api-docs/Interface.MarkdownRenderer.md). +This interface is essentially an extended typing of TypeDoc's [`Application`](https://typedoc.org/api/classes/Application.html) instance. ## Usage ```ts -import {MarkdownApplication} from 'typedoc-plugin-markdown'; +import { MarkdownApplication } from 'typedoc-plugin-markdown'; export function load(app: MarkdownApplication) { ... @@ -22,7 +20,11 @@ export function load(app: MarkdownApplication) { ### renderer -> **renderer**: [`MarkdownRenderer`](/api-docs/Interface.MarkdownRenderer.md) +```ts +renderer: MarkdownRenderer; +``` + +Re-types the `renderer` instance to [`MarkdownRenderer`](/api-docs/Interface.MarkdownRenderer.md). #### Overrides diff --git a/docs/pages/api-docs/Interface.MarkdownRenderer.md b/docs/pages/api-docs/Interface.MarkdownRenderer.md index e9421444f..4452a07d4 100644 --- a/docs/pages/api-docs/Interface.MarkdownRenderer.md +++ b/docs/pages/api-docs/Interface.MarkdownRenderer.md @@ -1,8 +1,6 @@ # MarkdownRenderer -An extended typing of TypeDoc's Renderer class. - -Includes updated typings for hooks and async jobs. +An extended typing of TypeDoc's [`Renderer`](https://typedoc.org/api/classes/Renderer.html) class that includes updated typings for hooks and async jobs. ## Usage @@ -15,12 +13,12 @@ app.renderer.markdownHooks.on( 'page.begin', () => '> This is some markdown at the top of the page', ); -app.renderer.preRenderAsyncJobs.push(async (event) => { - await doSomethingAsync(event); +app.renderer.preRenderAsyncJobs.push(async (output: MarkdownRendererEvent) => { + await doSomethingAsync(output); }); -app.renderer.postRenderAsyncJobs.push(async (event) => { - await doSomethingAsync(event); +app.renderer.postRenderAsyncJobs.push(async (output: MarkdownRendererEvent)) => { + await doSomethingAsync(output); }); } @@ -34,13 +32,21 @@ app.renderer.postRenderAsyncJobs.push(async (event) => { ### markdownHooks -> **markdownHooks**: [`EventHooks`](https://typedoc.org/api/classes/EventHooks.html)\<[`MarkdownRendererHooks`](/api-docs/Interface.MarkdownRendererHooks.md), `string`\> +```ts +markdownHooks: EventHooks; +``` + +Replaces the event hooks typings the [`MarkdownRendererHooks`](/api-docs/Interface.MarkdownRendererHooks.md) used by the plugin. *** ### preRenderAsyncJobs -> **preRenderAsyncJobs**: (`output`) => `Promise`\<`void`\>[] +```ts +preRenderAsyncJobs: (output) => Promise[]; +``` + +Re-types the returned argument argument to [`MarkdownRendererEvent`](/api-docs/Class.MarkdownRendererEvent.md). #### Overrides @@ -50,7 +56,11 @@ app.renderer.postRenderAsyncJobs.push(async (event) => { ### postRenderAsyncJobs -> **postRenderAsyncJobs**: (`output`) => `Promise`\<`void`\>[] +```ts +postRenderAsyncJobs: (output) => Promise[]; +``` + +Re-types the returned argument argument to [`MarkdownRendererEvent`](/api-docs/Class.MarkdownRendererEvent.md). #### Overrides diff --git a/docs/pages/api-docs/Interface.MarkdownRendererHooks.md b/docs/pages/api-docs/Interface.MarkdownRendererHooks.md index ffd0553f5..c762a8757 100644 --- a/docs/pages/api-docs/Interface.MarkdownRendererHooks.md +++ b/docs/pages/api-docs/Interface.MarkdownRendererHooks.md @@ -15,7 +15,9 @@ Describes the hooks available to inject output in the markdown theme. ### page.begin -> **page.begin**: [[`MarkdownThemeContext`](/api-docs/Class.MarkdownThemeContext.md)] +```ts +page.begin: [MarkdownThemeContext]; +``` Applied at the start of the markdown output. @@ -23,7 +25,9 @@ Applied at the start of the markdown output. ### page.end -> **page.end**: [[`MarkdownThemeContext`](/api-docs/Class.MarkdownThemeContext.md)] +```ts +page.end: [MarkdownThemeContext]; +``` Applied at the end of the markdown output. @@ -31,7 +35,9 @@ Applied at the end of the markdown output. ### content.begin -> **content.begin**: [[`MarkdownThemeContext`](/api-docs/Class.MarkdownThemeContext.md)] +```ts +content.begin: [MarkdownThemeContext]; +``` Applied before the main markdown content is rendered. @@ -39,7 +45,9 @@ Applied before the main markdown content is rendered. ### index.page.begin -> **index.page.begin**: [[`MarkdownThemeContext`](/api-docs/Class.MarkdownThemeContext.md)] +```ts +index.page.begin: [MarkdownThemeContext]; +``` Applied at the start of the markdown output on the index page. @@ -47,6 +55,8 @@ Applied at the start of the markdown output on the index page. ### index.page.end -> **index.page.end**: [[`MarkdownThemeContext`](/api-docs/Class.MarkdownThemeContext.md)] +```ts +index.page.end: [MarkdownThemeContext]; +``` Applied at the end of the markdown output on the index page. diff --git a/docs/pages/api-docs/Interface.NavigationItem.md b/docs/pages/api-docs/Interface.NavigationItem.md index 86a501cbc..1dac13b1b 100644 --- a/docs/pages/api-docs/Interface.NavigationItem.md +++ b/docs/pages/api-docs/Interface.NavigationItem.md @@ -6,22 +6,30 @@ The model used to define the navigation structure. ### title -> **title**: `string` +```ts +title: string; +``` *** ### path? -> `optional` **path**: `null` \| `string` +```ts +optional path: null | string; +``` *** ### kind? -> `optional` **kind**: [`ReflectionKind`](https://typedoc.org/api/enums/Models.ReflectionKind-1.html) +```ts +optional kind: ReflectionKind; +``` *** ### children? -> `optional` **children**: [`NavigationItem`](/api-docs/Interface.NavigationItem.md)[] +```ts +optional children: NavigationItem[]; +``` diff --git a/docs/pages/api-docs/Interface.PackageMetaData.md b/docs/pages/api-docs/Interface.PackageMetaData.md index b6881a56c..463e51292 100644 --- a/docs/pages/api-docs/Interface.PackageMetaData.md +++ b/docs/pages/api-docs/Interface.PackageMetaData.md @@ -6,10 +6,14 @@ The model used to define the package metadata when in packages mode. ### description -> **description**: `string` +```ts +description: string; +``` *** ### options -> **options**: [`Options`](https://typedoc.org/api/classes/Configuration.Options.html) +```ts +options: Options; +``` diff --git a/docs/pages/api-docs/Interface.PluginOptions.md b/docs/pages/api-docs/Interface.PluginOptions.md index f632d1038..3f0d298ca 100644 --- a/docs/pages/api-docs/Interface.PluginOptions.md +++ b/docs/pages/api-docs/Interface.PluginOptions.md @@ -6,7 +6,9 @@ Describes the options declared by the plugin. ### anchorPrefix -> **anchorPrefix**: `string` +```ts +anchorPrefix: string; +``` Custom anchor prefix when anchoring to in-page symbols. @@ -14,7 +16,9 @@ Custom anchor prefix when anchoring to in-page symbols. ### entryFileName -> **entryFileName**: `string` +```ts +entryFileName: string; +``` The file name of the entry page. @@ -22,7 +26,9 @@ The file name of the entry page. ### entryModule -> **entryModule**: `string` +```ts +entryModule: string; +``` The name of a module that should act as the root page for the documentation. @@ -30,7 +36,9 @@ The name of a module that should act as the root page for the documentation. ### enumMembersFormat -> **enumMembersFormat**: `"table"` \| `"list"` \| `"htmlTable"` +```ts +enumMembersFormat: "table" | "list" | "htmlTable"; +``` Specify the render style of enumeration members. @@ -38,7 +46,9 @@ Specify the render style of enumeration members. ### ~~excludeGroups~~ -> **excludeGroups**: `boolean` +```ts +excludeGroups: boolean; +``` #### Deprecated @@ -48,7 +58,9 @@ This option has been renamed hideGroupHeadings to better reflect its purpose. ### excludeScopesInPaths -> **excludeScopesInPaths**: `boolean` +```ts +excludeScopesInPaths: boolean; +``` Exclude writing @ scope directories in paths. @@ -56,7 +68,9 @@ Exclude writing @ scope directories in paths. ### expandObjects -> **expandObjects**: `boolean` +```ts +expandObjects: boolean; +``` Expand objects inside declarations. @@ -64,7 +78,9 @@ Expand objects inside declarations. ### expandParameters -> **expandParameters**: `boolean` +```ts +expandParameters: boolean; +``` Expand parameters in signature parentheses to display type information. @@ -72,7 +88,9 @@ Expand parameters in signature parentheses to display type information. ### fileExtension -> **fileExtension**: `string` +```ts +fileExtension: string; +``` Specify the file extension for generated output files. @@ -80,7 +98,9 @@ Specify the file extension for generated output files. ### flattenOutputFiles -> **flattenOutputFiles**: `boolean` +```ts +flattenOutputFiles: boolean; +``` Flatten output files to a single directory. @@ -88,7 +108,9 @@ Flatten output files to a single directory. ### hideBreadcrumbs -> **hideBreadcrumbs**: `boolean` +```ts +hideBreadcrumbs: boolean; +``` Do not print breadcrumbs. @@ -96,7 +118,9 @@ Do not print breadcrumbs. ### hideGroupHeadings -> **hideGroupHeadings**: `boolean` +```ts +hideGroupHeadings: boolean; +``` Excludes grouping by kind so all members are rendered and sorted at the same level. @@ -104,7 +128,9 @@ Excludes grouping by kind so all members are rendered and sorted at the same lev ### hidePageHeader -> **hidePageHeader**: `boolean` +```ts +hidePageHeader: boolean; +``` Do not print page header. @@ -112,7 +138,9 @@ Do not print page header. ### hidePageTitle -> **hidePageTitle**: `boolean` +```ts +hidePageTitle: boolean; +``` Do not print page title. @@ -120,31 +148,25 @@ Do not print page title. ### indexFormat -> **indexFormat**: `"table"` \| `"list"` \| `"htmlTable"` +```ts +indexFormat: "table" | "list"; +``` Specify the render format for index items. *** -### inlineDocuments - -> **inlineDocuments**: `boolean` - -Inline documents in pages. - -*** - -### leftAlignTableHeaders - -> **leftAlignTableHeaders**: `boolean` - -Left aligns items in table headers - -*** - ### membersWithOwnFile -> **membersWithOwnFile**: (`"Enum"` \| `"Variable"` \| `"Function"` \| `"Class"` \| `"Interface"` \| `"TypeAlias"`)[] +```ts +membersWithOwnFile: ( + | "Enum" + | "Variable" + | "Function" + | "Class" + | "Interface" + | "TypeAlias")[]; +``` Determines which members are exported to their own file when `outputFileStrategy` equals `members`. @@ -152,7 +174,9 @@ Determines which members are exported to their own file when `outputFileStrategy ### mergeReadme -> **mergeReadme**: `boolean` +```ts +mergeReadme: boolean; +``` Merges the resolved readme into the project index page. @@ -160,27 +184,41 @@ Merges the resolved readme into the project index page. ### navigationModel -> **navigationModel**: `object` +```ts +navigationModel: { + excludeGroups: boolean; + excludeCategories: boolean; + excludeFolders: boolean; +}; +``` Configures how the navigation model will be generated. #### excludeGroups -> **excludeGroups**: `boolean` +```ts +excludeGroups: boolean; +``` #### excludeCategories -> **excludeCategories**: `boolean` +```ts +excludeCategories: boolean; +``` #### excludeFolders -> **excludeFolders**: `boolean` +```ts +excludeFolders: boolean; +``` *** ### outputFileStrategy -> **outputFileStrategy**: `"members"` \| `"modules"` +```ts +outputFileStrategy: "members" | "modules"; +``` Determines how output files are generated. @@ -188,7 +226,9 @@ Determines how output files are generated. ### parametersFormat -> **parametersFormat**: `"table"` \| `"list"` \| `"htmlTable"` +```ts +parametersFormat: "table" | "list" | "htmlTable"; +``` Specify the render style of parameter and type parameter groups. @@ -196,7 +236,9 @@ Specify the render style of parameter and type parameter groups. ### preserveAnchorCasing -> **preserveAnchorCasing**: `boolean` +```ts +preserveAnchorCasing: boolean; +``` Preserve anchor casing when generating link to symbols. @@ -204,7 +246,9 @@ Preserve anchor casing when generating link to symbols. ### propertiesFormat -> **propertiesFormat**: `"table"` \| `"list"` \| `"htmlTable"` +```ts +propertiesFormat: "table" | "list" | "htmlTable"; +``` Specify the render style of property groups for interfaces and classes. @@ -212,7 +256,9 @@ Specify the render style of property groups for interfaces and classes. ### publicPath -> **publicPath**: `string` +```ts +publicPath: string; +``` Specify the base path for all urls. @@ -220,53 +266,132 @@ Specify the base path for all urls. ### sanitizeComments -> **sanitizeComments**: `boolean` +```ts +sanitizeComments: boolean; +``` Sanitize HTML and JSX inside JsDoc comments. *** -### tableColumnVisibility +### tableColumnSettings -> **tableColumnVisibility**: `object` +```ts +tableColumnSettings: { + hideDefaults: boolean; + hideInherited: boolean; + hideModifiers: boolean; + hideOverrides: boolean; + hideSources: boolean; + hideValues: boolean; + leftAlignHeaders: boolean; +}; +``` Control header alignment and column visibility in tables. #### hideDefaults -> **hideDefaults**: `boolean` +```ts +hideDefaults: boolean; +``` #### hideInherited -> **hideInherited**: `boolean` +```ts +hideInherited: boolean; +``` #### hideModifiers -> **hideModifiers**: `boolean` +```ts +hideModifiers: boolean; +``` #### hideOverrides -> **hideOverrides**: `boolean` +```ts +hideOverrides: boolean; +``` #### hideSources -> **hideSources**: `boolean` +```ts +hideSources: boolean; +``` + +#### hideValues + +```ts +hideValues: boolean; +``` + +#### leftAlignHeaders + +```ts +leftAlignHeaders: boolean; +``` *** -### ~~textContentMappings~~ +### textContentMappings -> **textContentMappings**: `Partial`\<`any`\> +```ts +textContentMappings: { + header.title: string; + header.docs: string; + breadcrumbs.home: string; + title.indexPage: string; + title.memberPage: string; + footer.text: string; +}; +``` -#### Deprecated +Change specific text placeholders in the template. + +#### header.title + +```ts +header.title: string; +``` + +#### header.docs + +```ts +header.docs: string; +``` + +#### breadcrumbs.home + +```ts +breadcrumbs.home: string; +``` + +#### title.indexPage + +```ts +title.indexPage: string; +``` + +#### title.memberPage + +```ts +title.memberPage: string; +``` + +#### footer.text -Provides a mechanism to change the content of text used in documentation. +```ts +footer.text: string; +``` *** ### typeDeclarationFormat -> **typeDeclarationFormat**: `"table"` \| `"list"` \| `"htmlTable"` +```ts +typeDeclarationFormat: "table" | "list" | "htmlTable"; +``` Specify the render style for type declaration members. @@ -274,7 +399,9 @@ Specify the render style for type declaration members. ### useCodeBlocks -> **useCodeBlocks**: `boolean` +```ts +useCodeBlocks: boolean; +``` Wraps signatures and declarations in code blocks. @@ -282,6 +409,8 @@ Wraps signatures and declarations in code blocks. ### useHTMLAnchors -> **useHTMLAnchors**: `boolean` +```ts +useHTMLAnchors: boolean; +``` Add HTML named anchors to headings and table rows. diff --git a/docs/pages/api-docs/Interface.UrlMapping.md b/docs/pages/api-docs/Interface.UrlMapping.md index ac3dec713..0e16564a2 100644 --- a/docs/pages/api-docs/Interface.UrlMapping.md +++ b/docs/pages/api-docs/Interface.UrlMapping.md @@ -6,19 +6,25 @@ The model used to define the URL mapping structure. ### url -> **url**: `string` +```ts +url: string; +``` *** ### model -> **model**: `Model` +```ts +model: Model; +``` *** ### template() -> **template**: (`data`) => `string` +```ts +template: (data) => string; +``` #### Parameters diff --git a/docs/pages/api-docs/index.md b/docs/pages/api-docs/index.md index 7feb4a0c5..3a33455df 100644 --- a/docs/pages/api-docs/index.md +++ b/docs/pages/api-docs/index.md @@ -1,6 +1,6 @@ # API -The public API of typedoc-plugin-markdown exposes some classes and types that can be used to customize the output of the plugin. Please note this only covers the API relevant to this plugin and not cover the entire [TypeDoc API](https://typedoc.org/api/). +The public API of typedoc-plugin-markdown exposes some classes and types that can be used to customize the output of the plugin. If you are interested in the TypeDoc API please visit [https://typedoc.org](https://typedoc.org/api/). The APIs are typically consumed by writing [local plugins](/docs/customizing-output#local-plugins). @@ -10,8 +10,8 @@ The Application class is the main entry point for a TypeDoc application and prov | Member | Description | | :------ | :------ | -| [MarkdownApplication](/api-docs/Interface.MarkdownApplication.md) | An extended typing of TypeDoc's Application instance. | -| [MarkdownRenderer](/api-docs/Interface.MarkdownRenderer.md) | An extended typing of TypeDoc's Renderer class. | +| [MarkdownApplication](/api-docs/Interface.MarkdownApplication.md) | This interface is essentially an extended typing of TypeDoc's [`Application`](https://typedoc.org/api/classes/Application.html) instance. | +| [MarkdownRenderer](/api-docs/Interface.MarkdownRenderer.md) | An extended typing of TypeDoc's [`Renderer`](https://typedoc.org/api/classes/Renderer.html) class that includes updated typings for hooks and async jobs. | | [MarkdownPageEvent](/api-docs/Class.MarkdownPageEvent.md) | An event emitted by before and after the markup of a page is rendered. | | [MarkdownRendererEvent](/api-docs/Class.MarkdownRendererEvent.md) | An event emitted at the beginning and end of the rendering process. | | [MarkdownRendererHooks](/api-docs/Interface.MarkdownRendererHooks.md) | Describes the hooks available to inject output in the markdown theme. | diff --git a/docs/pages/docs/CHANGELOG.md b/docs/pages/docs/CHANGELOG.md deleted file mode 100644 index 6236b6380..000000000 --- a/docs/pages/docs/CHANGELOG.md +++ /dev/null @@ -1,126 +0,0 @@ -# Changelog - -## 4.1 (2024-06-21) - -Version 4.1 introduces API compatibility fixes for TypeDoc 0.26. - -### New features - -#### TypeDoc 0.26 Feature Support - -##### Localization - -The plugin respects TypeDoc's 0.26 new localization model. For this reason the existing option `--textContentMappings` has been deprecated in favour of using this implementation. - -##### Documents - -The plugin respects TypeDoc's `@documents` implementation and attempts to follow a similar output structure. -In addition a new option [`--inlineDocuments`]() is available that will place documents in-place. - -#### Table Changes - -This release addresses some of the limitations of previous table implementations. - -Options effected are `--parametersFormat`, `--propertiesFormat`, `--enumMembersFormat`, `--typeDeclarationFormat` and `--indexFormat`, - -##### Markdown vs HTML tables - -Pure markdown have a limitation whereby block level elements can not render inside a cell. A workaround to this is an attempt to parse content into HTML, however this in itself is an anti pattern and introduces other issues (for example there is no way to ascertain how code blocks are handled by the host markdown parser). - -To overcome this issue a new key **"htmlTable"** which will wrap comments in an html table cell, which means that features such as code blocks can now render as intended and all parsing is the responsibility of the host's markdown parser. - -Please note this does involve an output change whereby all line breaks are now stripped from the existing **"table"** key. If you would like to preserve markdown block elements in tabular format please updated to use the **"htmlTable"** key. - -##### Additional Table Options - -Please two additional table options have been exposed: - -- **Column Visibility**: The option [`--tableColumnVisibility`]() introduces the ability to control what columns are displayed in output. This could be useful for some reflections that contain several columns. -- **Header alignment**: The plugin now does not define any header alignment by default. This typically results in table headers visually appearing center aligned. If you would prefer left align headers please use the [`--leftAlignTableHeaders`]() option. - -## 4.0.2 (2024-05-15) - -### Patch Changes - -- Fix symbol url anchors when "flattenOutputFiles" is "true" ([#616](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/616)) -- Normalize line breaks and tags within table columns ([#615](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/615)) -- Remove superfluous spaces and symbol on external links ([#614](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/614)) -- Escape all angle brackets with "santizeComments" ([#612](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/612)) -- Correctly handle quoted symbol names ([#611](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/611)) -- Correctly handle excludeScopesInPaths in windows ([#610](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/610)) - -## 4.0.1 (2024-05-07) - -### Patch Changes - -- Remove superfluous newlines from table column descriptions ([#591](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/591)). -- Handle multiple `@example` tags on same reflection. -- Fix missing extended by definitions. -- Escape Symbols with signatures correctly. - -## 4.0.0 (2024-05-03) - -> v4 is a major release that includes a number of bug fixes, new features and UI improvements. - -### Architectural Changes - -- Handlebars as a dependency has been removed. -- Updated customization model with the ability to set hooks, events and custom theming. -- Exposed navigation structure. - -### Features - -- Updated output file structure. -- Improved and cleaner UI. -- A set of updated and additional new options with comprehensive documentation. -- Exported option types and JSON schema. - -### Structural Changes - -- Each module member is now output to its own file by default. See option `--outputFileStrategy`. To achieve the same output as v3 (whereby only Classes, Enums and Interfaces have their own file), set the option `membersWithOwnFile` option. -- Parameters are output as a list by default. To achieve the same output as v3 (where parameters are output as a table), use option `--parametersFormat=table`. - -### Breaking Changes - -- Because the file structure has changed you may need to update any cross references to files in your documentation. -- Setting `theme` to `"markdown"` is no longer required and should be removed. -- The option `indexTitle` has been removed. Please use the `"title.indexPage"` key with option `--textContentMappings`. -- The option `allReflectionsHaveOwnDocument` has been removed (this behaviour is now the default). Please see option `outputFileStrategy`](/docs/options#outputfilestrategy). -- The option `entryDocument` has been renamed to `entryFileName` to better reflect its purpose. -- The option `namedAnchors` has been renamed to `useHTMLAnchors` to better reflect its purpose. -- The option `hideInPageTOC` has been removed. In-page TOC are no longer included by default. You can include in-page TOCs by using `typedoc-plugin-remark` and the `remark-toc` plugin. -- The option `objectLiteralTypeDeclarationStyle` has been removed. Please use option `--typeDeclarationFormat=list`. - -### Bug Fixes - -- Duplication in callback/callable/function properties. ([#581](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/581)). -- @experimental / @internal annotations. ([#556](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/556)) -- Fix events output and strike-through deprecated items. ([#534](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/534)) -- Class static functions are no longer marked. ([#533](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/533)) -- @example block not rendered with Headline ([#501](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/501)) -- Support for categories ([#499](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/499)) -- Correctly resolve package readme urls from member pages. ([#483](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/483)) -- Add the ability to add a separate frontmatter for readme file. ([#469](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/469)) -- Items in tables are not linkable. ([#463](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/463)) -- Custom i18n texts. ([#458](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/458)) -- How to improve the formatting for types?. ([#456](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/456)) -- How to change title format. ([#450](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/450)) -- Export Docusaurus plugin options type. ([#440](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/440)) -- How to export interface as a table. ([#403](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/403)) -- Broken Link caused by Typescript class being defined in an index file. ([#402](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/403)) -- Markdown plugin inserts unnecessary escape characters. ([#398](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/398)) -- Potential bug with optional function argument. ([#396](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/396)) -- Respect monorepo `readmeFile` configuration ([#383](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/383)) -- Embed all objects under a Module/Namespace onto single page. ([#338](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/338)) -- Extra spaces when merging lines in a table. ([#331](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/331)) -- Does not support namespace (or module) and interface with same name. ([#300](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/300)) -- Integration with VitePress? ([#287](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/287)) -- Typedoc comments with text wrapped in `<` and `>` breaks Docusaurus Markdown parser. ([#276](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/276)) -- Navigation support? ([#262](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/262)) -- Sidebar Category Support? ([#213](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/213)) -- Properties as Table like function properties. ([#109](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/109)) -- Provide a link/excerpt/screenshot to a demo/example rendered output ([#102](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/102)) - ---- - -Earlier changelog entries can be found in `CHANGELOG_ARCHIVE.md`. diff --git a/docs/pages/docs/_meta.js b/docs/pages/docs/_meta.js index f4a8d0752..397720025 100644 --- a/docs/pages/docs/_meta.js +++ b/docs/pages/docs/_meta.js @@ -11,12 +11,12 @@ export default { title: 'Guides', }, 'typedoc-usage': '', + internationalization: '', 'customizing-output': '', '-- Support': { type: 'separator', title: 'Support', }, versioning: '', - CHANGELOG: '', - 'migration-guide': 'Migration Guide V4', + changelog: 'Changelog', }; diff --git a/docs/pages/docs/migration-guide.mdx b/docs/pages/docs/changelog/4.0.mdx similarity index 85% rename from docs/pages/docs/migration-guide.mdx rename to docs/pages/docs/changelog/4.0.mdx index 86d02a90b..67fe368f7 100644 --- a/docs/pages/docs/migration-guide.mdx +++ b/docs/pages/docs/changelog/4.0.mdx @@ -1,19 +1,19 @@ import { Callout } from 'nextra/components'; -# 🚀 Migration Guide V4 +# 4.0 (May 2024) - - v4 is a major release that includes a number of bug fixes, new features and UX - improvements. + + v4.0 is a major release that includes a number of bug fixes, new features and + UX improvements. -## 🏗 Architectural Changes +## Architectural Changes - Handlebars as a dependency has been removed. - Updated customization model with the ability to set hooks, events and custom theming. - Improved test and linting coverage. -## 🌟 New Features +## New Features - Updated output file structure. - Improved and cleaner UX configurable with options. @@ -22,13 +22,13 @@ import { Callout } from 'nextra/components'; - Ability to customize static text. - Comprehensive documentation and examples repository. -## 🏗️ Non-Breaking Changes +## Non-Breaking Changes - Each module member is now output to its own file by default. See [`outputFileStrategy`](/docs/options#outputfilestrategy). To achieve the same output as v3 (whereby only Classes, Enums and Interfaces have their own file), set the [`membersWithOwnFile`](/docs/options#memberswithownfile) option. - Parameters are output as a list by default. To achieve the same output as v3 (where parameters are output as a table), use [`parametersFormat=table`](/docs/options#parametersformat). - Comment `@` tags are now displayed as headings. -## 💥 Breaking Changes +## Breaking Changes - The output file structure has changed so you may need to update any cross references into your docs from external sources. - Setting `theme` to `"markdown"` is not required and should be removed. @@ -39,10 +39,16 @@ import { Callout } from 'nextra/components'; - The option `hideInPageTOC` has been removed. In-page TOC are no longer included by default. You can include in-page TOCs by using [typedoc-plugin-remark](/plugins/remark) and the [remark-toc](plugins/remark/suggested-plugins#remark-toc) plugin. - The option `objectLiteralTypeDeclarationStyle` has been removed. Please use [`typeDeclarationFormat=list`](/docs/options#typedeclarationformat). -## 🗨️ Feedback +## Feedback Feedback on the this release is welcome and encouraged. If you'd like to report a bug, raise a feature request or have any questions, please [open an issue](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/new/choose). -## 👍 Thank You +## Thank You A big thank you to all the members of the community who helped make this release possible with direct contributions and providing invaluable user testing and feedback! + +--- + +Browse the [GitHub +changelog](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/CHANGELOG.md) +for the full list of changes. diff --git a/docs/pages/docs/changelog/4.1.mdx b/docs/pages/docs/changelog/4.1.mdx new file mode 100644 index 000000000..10c88f947 --- /dev/null +++ b/docs/pages/docs/changelog/4.1.mdx @@ -0,0 +1,31 @@ +import { Callout } from 'nextra/components'; + +# 4.1 (June 2024) + + +v4.1 introduces [TypeDoc v0.26]() API and feature support and more. + + + +## New Features + +This release contains required internal api fixes and theme updates to support TypeDoc 0.26 in addition to some additional table options. New supported features includes: + +- **Localization**: Theme support for TypeDoc's 0.26 localization model. +- **Documents**: Theme support for TypeDoc's 0.26 @documents implementation. +- **HTML tables**: Pure markdown tables have a limitation whereby they can not contain block markdown elements. To work around this issue a new key `"htmlTable"` is exposed to format options which will wrap comments in an html table cell and all parsing is the responsibility of the host's markdown parser. + This means that elements such as code blocks can now render as intended inside table cells. Affected options are `parametersFormat`, `propertiesFormat`, `typeDeclarationFormat` and `enumMembersFormat`. +- **Column configuration**: The plugin now supports the ability to control what columns are displayed in output with the [`--tableColumnSettings`]() option. + +## Non-Breaking Changes + +- **Markdown tables**: All line breaks are now stripped from the existing `"table"` key. If you would like to preserve markdown block elements in tabular format please updated to use the `"htmlTable"` key. +- **Table header alignment**: The plugin now does not define any header alignment by default. This typically results in table headers visually appearing center aligned. If you would prefer left align headers please configure using the [`--tableColumnSettings `]() option. +- **Text labels**: The `--textContentMappings` option is now only used for configuring static text labels and placeholders where alternative content might be preferred. + All other general content labels are now controlled by the TypeDoc localization model. + +--- + +Browse the [GitHub +changelog](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/CHANGELOG.md) +for the full list of changes. diff --git a/docs/pages/docs/changelog/_meta.js b/docs/pages/docs/changelog/_meta.js new file mode 100644 index 000000000..9a3e65f01 --- /dev/null +++ b/docs/pages/docs/changelog/_meta.js @@ -0,0 +1,4 @@ +export default { + 4.1: '', + '4.0': '', +}; diff --git a/docs/pages/docs/internationalization.mdx b/docs/pages/docs/internationalization.mdx new file mode 100644 index 000000000..93fe4cdd0 --- /dev/null +++ b/docs/pages/docs/internationalization.mdx @@ -0,0 +1,3 @@ +# Internationalization + +Please follow the TypeDoc documentation for [Internationalization](https://typedoc.org/guides/options/#internationalization) for more information. diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx index 100d4968e..329ba15ec 100644 --- a/docs/pages/docs/options.mdx +++ b/docs/pages/docs/options.mdx @@ -19,7 +19,6 @@ Options that are used to configure how files are output. - [--entryModule](./options/file-options.mdx#--entrymodule) - [--excludeScopesInPaths](./options/file-options.mdx#--excludescopesinpaths) - [--mergeReadme](./options/file-options.mdx#--mergereadme) -- [--inlineDocuments](./options/file-options.mdx#--inlinedocuments) ## Display Options @@ -37,8 +36,7 @@ Options that are used to configure how the output is structured and displayed . - [--enumMembersFormat](./options/display-options.mdx#--enummembersformat) - [--typeDeclarationFormat](./options/display-options.mdx#--typedeclarationformat) - [--indexFormat](./options/display-options.mdx#--indexformat) -- [--tableColumnVisibility](./options/display-options.mdx#--tablecolumnvisibility) -- [--leftAlignTableHeaders](./options/display-options.mdx#--leftaligntableheaders) +- [--tableColumnSettings](./options/display-options.mdx#--tablecolumnsettings) ## Utility Options @@ -50,4 +48,4 @@ Options that are used for general configuration and utility purposes. - [--useHTMLAnchors](./options/utility-options.mdx#--usehtmlanchors) - [--preserveAnchorCasing](./options/utility-options.mdx#--preserveanchorcasing) - [--navigationModel](./options/utility-options.mdx#--navigationmodel) -- [~--textContentMappings~](./options/utility-options.mdx#--textcontentmappings) +- [--textContentMappings](./options/utility-options.mdx#--textcontentmappings) diff --git a/docs/pages/docs/options/display-options.mdx b/docs/pages/docs/options/display-options.mdx index 742534d8b..c8c410fdc 100644 --- a/docs/pages/docs/options/display-options.mdx +++ b/docs/pages/docs/options/display-options.mdx @@ -121,7 +121,7 @@ This option specifies the output format for parameters and type parameters of fu - **"list"**: parameters are output as bullet points in a linear list, suitable for more detailed comments. - **"table"**: parameters are output within a markdown table, condensed into a single paragraph. -- **"htmlTable"**: parameters are output in an HTML table, enabling block elements to render in tabular format. +- **"htmlTable"**: parameters are output in an HTML table, enabling block elements to render in tabular format ```json filename="typedoc.json" { @@ -191,11 +191,15 @@ This option specifies the output format for type declaration: Specify the render format for index items. -> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. +> Accepts either `"list"` or `"table"`. Defaults to `"list"`. + +This option renders index items either as a simple unordered list or in a table. -This option renders index items either as a simple list or in a table with a description column exposing the comment summary. +When table style is selected the following will be the behaviour: -For a packages index page (when `--entryPointStrategy` equals `packages`), the package.json description will be displayed with an additional "Version" column (when `--includeVersion` equals true). +- For a **members index**, a description column will be added to the table with the first paragraph of the comment summary. +- For a **packages index**, (when `--entryPointStrategy` equals `packages`), the package.json description will be displayed with an additional "Version" column (when `--includeVersion` equals true). +- For a **documents index** a description column will be added to the table printing the `description` frontmatter if present. ```json filename="typedoc.json" { @@ -203,7 +207,7 @@ For a packages index page (when `--entryPointStrategy` equals `packages`), the p } ``` -## --tableColumnVisibility +## --tableColumnSettings Control header alignment and column visibility in tables. @@ -211,34 +215,21 @@ For a packages index page (when `--entryPointStrategy` equals `packages`), the p > -By default, all available data for symbols are displayed in table columns. +By default, all available data for symbols are displayed in table columns. For some reflections this can result in several columns. This option allows you to control the visibility of columns, prioritizing readability over displaying complete data. +In addition you can control the alignment of the header text. ```json filename="typedoc.json" { - "tableColumnVisibility": { + "tableColumnSettings": { "hideDefaults": false, "hideInherited": false, "hideModifiers": false, "hideOverrides": false, - "hideSources": false + "hideSources": false, + "hideValues": false, + "leftAlignHeaders": false } } ``` - -## --leftAlignTableHeaders - -Left aligns items in table headers - -> Accepts a boolean value. Defaults to `false`. - -By default table alignment is not specified which means the table headings will typically be centred. - -This options can be used to specify left alignment for table headings. - -```json filename="typedoc.json" -{ - "leftAlignTableHeaders": false -} -``` diff --git a/docs/pages/docs/options/file-options.mdx b/docs/pages/docs/options/file-options.mdx index 9e6ce2aca..900dca5b8 100644 --- a/docs/pages/docs/options/file-options.mdx +++ b/docs/pages/docs/options/file-options.mdx @@ -213,7 +213,11 @@ Ignored if `flattenOutputFiles` is set to `true`. > Accepts a boolean value. Defaults to `false`. -By default when a readme file is resolved, a separate readme page is created. This option appends the index page to the readme so only a single root page is generated. +By default when a readme file is resolved, a separate readme page is created. +This option appends the index page to the readme so only a single root page is generated. + +You can additionally configure the generated title with `"textContentMappings": { "title.indexPage" : "My API"}`. +See [`--textContentMappings`](/docs/options/utility-options#--textcontentmappings). This option has no effect when [`readme`](https://typedoc.org/options/input/#readme) is set to `"none"`. @@ -222,19 +226,3 @@ This option has no effect when [`readme`](https://typedoc.org/options/input/#rea "mergeReadme": false } ``` - -## --inlineDocuments - -Inline documents in pages. - -> Accepts a boolean value. Defaults to `false`. - -By default a documents indexes and separate documents pages are generated when using the `@document` tag. - -This option inlines the document into the page rather than generating a separate document page. - -```json filename="typedoc.json" -{ - "inlineDocuments": false -} -``` diff --git a/docs/pages/docs/options/utility-options.mdx b/docs/pages/docs/options/utility-options.mdx index 2b9ced3e9..a53b166c0 100644 --- a/docs/pages/docs/options/utility-options.mdx +++ b/docs/pages/docs/options/utility-options.mdx @@ -134,19 +134,32 @@ export function load(app: MarkdownApplication) { } ``` -## ~--textContentMappings~ +## --textContentMappings - - Deprecated: This option has been deprecated in favour of TypeDoc's 0.26 - localization feature. - +Change specific text placeholders in the template. + +> -> Accepts a key/value object. +Defines placeholder text in main template that can be customized. Includes the main page header and breadcrumbs (if displayed), +page titles and page footer. -This option enables changing static text rendered to the documentation. +Default values within curly braces {} indicates a placeholder of dynamic text. + +- The `{projectName}` placeholder writes project's name . +- The `{kind}` writes the reflection kind of the page. +- The `{version}` placeholder writes package version (if includeVersion is `true`). + +If you are looking for general localization support please see [localization](). ```json filename="typedoc.json" { - "textContentMappings": {} + "textContentMappings": { + "header.title": "{projectName} {version}", + "header.docs": "Docs", + "breadcrumbs.home": "{projectName} {version}", + "title.indexPage": "{projectName} {version}", + "title.memberPage": "{kind}: {name}", + "footer.text": "" + } } ``` diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx index 49139e8f3..25b704a79 100644 --- a/docs/theme.config.jsx +++ b/docs/theme.config.jsx @@ -35,7 +35,7 @@ export default { content: ( <> 🎉{' '} - + v4.1 released • Find out more! diff --git a/package-lock.json b/package-lock.json index 14e8873a8..83039ae2d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -44,7 +44,7 @@ "ts-morph": "^22.0.0", "ts-node": "^10.9.2", "tsc-alias": "^1.8.10", - "typedoc": "^0.26.0-beta.1", + "typedoc": "^0.26.0-beta.2", "typescript": "^5.4.5", "unified-prettier": "^2.0.1" } @@ -5049,9 +5049,9 @@ "dev": true }, "node_modules/@shikijs/core": { - "version": "1.5.2", - "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.5.2.tgz", - "integrity": "sha512-wSAOgaz48GmhILFElMCeQypSZmj6Ru6DttOOtl3KNkdJ17ApQuGNCfzpk4cClasVrnIu45++2DBwG4LNMQAfaA==" + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.6.1.tgz", + "integrity": "sha512-CqYyepN4SnBopaoXYwng4NO8riB5ask/LTCkhOFq+GNGtr2X+aKeD767eYdqYukeixEUvv4bXdyTYVaogj7KBw==" }, "node_modules/@sideway/address": { "version": "4.1.5", @@ -20137,11 +20137,11 @@ } }, "node_modules/shiki": { - "version": "1.5.2", - "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.5.2.tgz", - "integrity": "sha512-fpPbuSaatinmdGijE7VYUD3hxLozR3ZZ+iAx8Iy2X6REmJGyF5hQl94SgmiUNTospq346nXUVZx0035dyGvIVw==", + "version": "1.6.1", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.6.1.tgz", + "integrity": "sha512-1Pu/A1rtsG6HZvQm4W0NExQ45e02og+rPog7PDaFDiMumZgOYnZIu4JtGQeAIfMwdbKSjJQoCUr79vDLKUUxWA==", "dependencies": { - "@shikijs/core": "1.5.2" + "@shikijs/core": "1.6.1" } }, "node_modules/side-channel": { @@ -21846,14 +21846,14 @@ } }, "node_modules/typedoc": { - "version": "0.26.0-beta.1", - "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.0-beta.1.tgz", - "integrity": "sha512-bnTZHxgvGQusWGEZyyzzaxD6Q1+8UQcEksT3PmN8jtgpWu1b1/Kb2Ib4jbpErHUabMR0+9088EH5eFolMN0RQA==", + "version": "0.26.0-beta.2", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.0-beta.2.tgz", + "integrity": "sha512-sFVUArw13cF8K7jeayUXyVCby9pRsEdjkQSvgnRxL8Wzuow9G7xlrXBhWU1BFBoGK8RC25hXD/4oJmMQhnnEnQ==", "dependencies": { "lunr": "^2.3.9", "markdown-it": "^14.1.0", "minimatch": "^9.0.4", - "shiki": "^1.4.0", + "shiki": "^1.6.0", "yaml": "^2.4.2" }, "bin": { @@ -23395,7 +23395,7 @@ } }, "packages/typedoc-plugin-markdown": { - "version": "4.0.2", + "version": "4.0.3", "license": "MIT", "engines": { "node": ">= 18" @@ -23405,7 +23405,7 @@ } }, "packages/typedoc-plugin-remark": { - "version": "1.0.0", + "version": "1.0.1", "license": "MIT", "dependencies": { "remark": "^15.0.1", diff --git a/package.json b/package.json index 08cbe377b..cf8d66327 100644 --- a/package.json +++ b/package.json @@ -48,7 +48,7 @@ "ts-morph": "^22.0.0", "ts-node": "^10.9.2", "tsc-alias": "^1.8.10", - "typedoc": "^0.26.0-beta.1", + "typedoc": "^0.26.0-beta.2", "typescript": "^5.4.5", "unified-prettier": "^2.0.1" } diff --git a/packages/docusaurus-plugin-typedoc/package.json b/packages/docusaurus-plugin-typedoc/package.json index ddc6f0d2d..bdd0fbf4e 100644 --- a/packages/docusaurus-plugin-typedoc/package.json +++ b/packages/docusaurus-plugin-typedoc/package.json @@ -14,7 +14,7 @@ "url": "git+https://github.com/typedoc2md/typedoc-plugin-markdown.git", "directory": "packages/docusaurus-plugin-typedoc" }, - "homepage": "http://typedoc.org/plugins/docusaurus", + "homepage": "http://typedoc-plugin-markdown.org/plugins/docusaurus", "peerDependencies": { "typedoc-plugin-markdown": ">=4.0.0" }, diff --git a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap index a30259b8c..243ec0ec0 100644 --- a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap +++ b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap @@ -64,7 +64,7 @@ Links using \`{@link}\` inline tags. - [Links to CommentInterface.prop](index.md#prop) - [Links to CommentInterface.propb](index.md#propb) -#### Extended By +#### Extended by - [\`CommentInterfaceExtended\`](index.md#commentinterfaceextended) diff --git a/packages/typedoc-plugin-markdown/.docs/plugins/typedoc-symbol-resolver.mjs b/packages/typedoc-plugin-markdown/.docs/plugins/typedoc-symbol-resolver.mjs deleted file mode 100644 index eb21a2a95..000000000 --- a/packages/typedoc-plugin-markdown/.docs/plugins/typedoc-symbol-resolver.mjs +++ /dev/null @@ -1,18 +0,0 @@ -// @ts-check - -/** - * Local plugin to tweak TypeDoc output for nextra docs - * - * @param {import("typedoc-plugin-markdown").MarkdownApplication} app - */ -export function load(app) { - app.converter.addUnknownSymbolResolver((ref) => { - if (ref?.symbolReference?.path && ref.moduleSource !== 'typedoc') { - const name = ref?.symbolReference?.path[0].path; - return { - target: `https://typedoc.org/api/classes/${name}`, - caption: name, - }; - } - }); -} diff --git a/packages/typedoc-plugin-markdown/.docs/typedoc.html.json b/packages/typedoc-plugin-markdown/.docs/typedoc.html.json new file mode 100644 index 000000000..ba17b1787 --- /dev/null +++ b/packages/typedoc-plugin-markdown/.docs/typedoc.html.json @@ -0,0 +1,80 @@ +{ + "entryPoints": ["../src/public-api.ts"], + "plugin": [ + "./plugins/typedoc-nextra.mjs", + "./plugins/typedoc-ignore-typeparam.mjs" + ], + "out": "./html", + "sortEntryPoints": false, + "name": "API", + "readme": "none", + "sort": ["required-first", "source-order"], + "includeVersion": false, + "categoryOrder": [ + "Application", + "Theme", + "Options", + "Page Partials", + "Container Partials", + "Member Partials", + "Comment Partials", + "Type Partials", + "*" + ], + "disableSources": true, + "excludeInternal": true, + "excludeExternals": true, + "excludePrivate": true, + "navigation": { + "includeCategories": true, + "includeGroups": false + }, + "externalSymbolLinkMappings": { + "typedoc": { + "ArrayType": "https://typedoc.org/api/types/Models.ArrayType.html", + "Application": "https://typedoc.org/api/classes/Application.html", + "Comment": "https://typedoc.org/api/types/Models.Comment.html", + "CommentDisplayPart": "https://typedoc.org/api/types/Models.CommentDisplayPart.html", + "ConditionalType": "https://typedoc.org/api/types/Models.ConditionalType.html", + "ContainerReflection": "https://typedoc.org/api/classes/Models.ContainerReflection.html", + "DeclarationHierarchy": "https://typedoc.org/api/classes/Models.DeclarationHierarchy.html", + "DeclarationReflection": "https://typedoc.org/api/classes/Models.DeclarationReflection.html", + "DefaultThemeRenderContext": "https://typedoc.org/api/classes/DefaultThemeRenderContext.html", + "Event": "https://typedoc.org/api/classes/Event.html", + "EventHooks": "https://typedoc.org/api/classes/EventHooks.html", + "IndexedAccessType": "https://typedoc.org/api/types/Models.IndexedAccessType.html", + "InferredType": "https://typedoc.org/api/types/Models.InferredType.html", + "IntersectionType": "https://typedoc.org/api/types/Models.IntersectionType.html", + "IntrinsicType": "https://typedoc.org/api/types/Models.IntrinsicType.html", + "LiteralType": "https://typedoc.org/api/types/Models.LiteralType.html", + "NamedTupleMember": "https://typedoc.org/api/types/Models.NamedTupleMember.html", + "ManuallyValidatedOption": "https://typedoc.org/api/types/Configuration.ManuallyValidatedOption.html", + "Options": "https://typedoc.org/api/classes/Configuration.Options.html", + "PageEvent": "https://typedoc.org/api/classes/PageEvent.html", + "ParameterReflection": "https://typedoc.org/api/classes/Models.ParameterReflection.html", + "ProjectReflection": "https://typedoc.org/api/classes/Models.ProjectReflection.html", + "ReferenceReflection": "https://typedoc.org/api/classes/Models.ReferenceReflection.html", + "ReferenceType": "https://typedoc.org/api/classes/Models.ReferenceType.html", + "Renderer": "https://typedoc.org/api/classes/Renderer.html", + "RendererEvent": "https://typedoc.org/api/classes/RendererEvent.html", + "RenderTemplate": "https://typedoc.org/api/types/RenderTemplate.html", + "Reflection": "https://typedoc.org/api/classes/Models.Reflection.html", + "ReflectionCategory": "https://typedoc.org/api/types/Models.ReflectionCategory.html", + "ReflectionFlags": "https://typedoc.org/api/classes/Models.ReflectionFlags.html", + "ReflectionGroup": "https://typedoc.org/api/classes/Models.ReflectionGroup.html", + "ReflectionKind": "https://typedoc.org/api/enums/Models.ReflectionKind-1.html", + "ReflectionType": "https://typedoc.org/api/classes/Models.ReflectionType.html", + "SignatureReflection": "https://typedoc.org/api/classes/Models.SignatureReflection.html", + "SomeType": "https://typedoc.org/api/classes/Models.SomeType.html", + "TypeParameterReflection": "https://typedoc.org/api/classes/Models.TypeParameterReflection.html", + "Theme": "https://typedoc.org/api/classes/Theme.html", + "TypeDocOptions": "https://typedoc.org/api/interfaces/TypeDocOptions.html", + "TypeOperatorType": "https://typedoc.org/api/interfaces/TypeOperatorType.html", + "TupleType": "https://typedoc.org/api/classes/Models.TupleType.html", + "QueryType": "https://typedoc.org/api/types/Models.QueryType.html", + "UnknownType": "https://typedoc.org/api/types/Models.UnknownType.html", + "UnionType": "https://typedoc.org/api/types/Models.UnionType.html", + "UrlMapping": "https://typedoc.org/api/classes/UrlMapping.html" + } + } +} diff --git a/packages/typedoc-plugin-markdown/.docs/typedoc.json b/packages/typedoc-plugin-markdown/.docs/typedoc.json index baaa0cd61..77c3567a0 100644 --- a/packages/typedoc-plugin-markdown/.docs/typedoc.json +++ b/packages/typedoc-plugin-markdown/.docs/typedoc.json @@ -9,14 +9,22 @@ "publicPath": "/api-docs", "indexFormat": "table", "mergeReadme": true, - "leftAlignTableHeaders": true, "entryFileName": "index.md", "hideBreadcrumbs": true, "hidePageHeader": true, "excludeGroups": true, + "expandObjects": true, "parametersFormat": "table", + "expandParameters": false, + "tableColumnSettings": { + "hideOverrides": true, + "hideModifiers": true, + "hideDefaults": true, + "hideSources": true, + "leftAlignHeaders": true + }, "outputFileStrategy": "members", - "useCodeBlocks": false, + "useCodeBlocks": true, "textContentMappings": { "title.memberPage": "{name}" }, diff --git a/packages/typedoc-plugin-markdown/.scripts/prebuild-kinds.ts b/packages/typedoc-plugin-markdown/.scripts/prebuild-kinds.ts deleted file mode 100644 index ab20b3aca..000000000 --- a/packages/typedoc-plugin-markdown/.scripts/prebuild-kinds.ts +++ /dev/null @@ -1,90 +0,0 @@ -import * as fs from 'fs'; -import * as path from 'path'; -import * as prettier from 'prettier'; -import { ReflectionKind } from 'typedoc'; - -export async function prebuildKinds() { - const themeRenderKindConstantsFile = path.join( - __dirname, - '..', - 'src', - 'options', - 'text-mappings', - 'kind-defaults.ts', - ); - - const kinds = [ - { key: 'accessor', kind: ReflectionKind.Accessor }, - { key: 'class', kind: ReflectionKind.Class }, - { key: 'constructor', kind: ReflectionKind.Constructor }, - { key: 'enum', kind: ReflectionKind.Enum }, - { key: 'enumMember', kind: ReflectionKind.EnumMember }, - { key: 'event', kind: undefined }, - { key: 'function', kind: ReflectionKind.Function }, - { key: 'interface', kind: ReflectionKind.Interface }, - { key: 'method', kind: ReflectionKind.Method }, - { key: 'module', kind: ReflectionKind.Module }, - { key: 'namespace', kind: ReflectionKind.Namespace }, - { key: 'variable', kind: ReflectionKind.Variable }, - { key: 'parameter', kind: ReflectionKind.Parameter }, - { key: 'property', kind: ReflectionKind.Property }, - { key: 'reference', kind: ReflectionKind.Reference }, - { key: 'typeAlias', kind: ReflectionKind.TypeAlias }, - { key: 'typeParameter', kind: ReflectionKind.TypeParameter }, - ]; - - const kindsString: string[] = []; - - const capitalize = (s: string) => s && s[0].toUpperCase() + s.slice(1); - - const singularString = (kind: any) => - kind.kind ? ReflectionKind.singularString(kind.kind) : capitalize(kind.key); - - const pluralString = (kind: any) => - kind.kind - ? ReflectionKind.pluralString(kind.kind) - : `${capitalize(kind.key)}s`; - - kindsString.push(` - // THIS FILE IS AUTOGENERATED - DO NOT EDIT DIRECTLY - - export const KIND_DEFAULTS: Record = { - ${kinds - .map((kind) => { - return ` - 'kind.${kind.key}.singular':'${singularString(kind)}', - 'kind.${kind.key}.plural':'${pluralString(kind)}' - `; - }) - .join(',')} - } - `); - - kindsString.push(` - export const SINGULAR_KIND_KEY_MAP: Record = { - ${kinds - .map((kind) => { - return `['${singularString(kind)}']: 'kind.${kind.key}.singular'`; - }) - .join(',')} - } - `); - - kindsString.push(` - export const PLURAL_KIND_KEY_MAP: Record= { - ${kinds - .map((kind) => { - return `['${pluralString(kind)}']: 'kind.${kind.key}.plural'`; - }) - .join(',')} - } - `); - - const formattedKinds = await prettier.format(kindsString.join('\n'), { - parser: 'typescript', - singleQuote: true, - trailingComma: 'all', - }); - - fs.writeFileSync(themeRenderKindConstantsFile, formattedKinds); -} diff --git a/packages/typedoc-plugin-markdown/.scripts/prebuild-resources.ts b/packages/typedoc-plugin-markdown/.scripts/prebuild-resources.ts index 2c7bd7816..1e73ce7d7 100644 --- a/packages/typedoc-plugin-markdown/.scripts/prebuild-resources.ts +++ b/packages/typedoc-plugin-markdown/.scripts/prebuild-resources.ts @@ -37,23 +37,27 @@ function getSymbols(files: string[], type: string, thePath = resourcesPath) { ?.getParameters() .filter((parameter) => parameter.getName() !== 'context') .map((parameter) => { - const typeunions = parameter - .getType() - .getText() - .split('|') - .map((unions) => { - const union = unions.split('.'); - const isKeyOf = union[0].startsWith('keyof'); - if (union[1] && union[1].startsWith('MarkdownPageEvent')) { - return `MarkdownPageEvent<${union[union.length - 1]}`; - } - const typeParts: string[] = []; - if (isKeyOf) { - typeParts.push('keyof'); - } - typeParts.push(union[union.length - 1]); - return typeParts.join(' '); - }); + let parameterTextType = parameter.getType().getText(); + if (parameterTextType.startsWith('{')) { + parameterTextType = parameterTextType.replace( + /import\(".*"\)\.([a-zA-Z_][a-zA-Z0-9_]*)/g, + '$1', + ); + } + const typeunions = parameterTextType.split('|').map((unions) => { + const union = unions.split('.'); + const isKeyOf = union[0].startsWith('keyof'); + if (union[1] && union[1].startsWith('MarkdownPageEvent')) { + return `MarkdownPageEvent<${union[union.length - 1]}`; + } + const typeParts: string[] = []; + if (isKeyOf) { + typeParts.push('keyof'); + } + typeParts.push(union[union.length - 1]); + return typeParts.join(' '); + }); + const name = parameter.getName(); const isOptional = parameter.isOptional(); const initializer = parameter.getInitializer(); diff --git a/packages/typedoc-plugin-markdown/package.json b/packages/typedoc-plugin-markdown/package.json index 8452738a2..1b6ef22da 100644 --- a/packages/typedoc-plugin-markdown/package.json +++ b/packages/typedoc-plugin-markdown/package.json @@ -19,7 +19,7 @@ "test:update": "npm run build && npm run test -- -u", "support": "npm run schema && npm run docs", "schema": "ts-node ./.scripts/schema/generate-schema.ts", - "docs": "npm run build && typedoc --options ./.docs/typedoc.json" + "docs": "npm run build && typedoc --options ./.docs/typedoc.json && typedoc --options ./.docs/typedoc.html.json" }, "author": "Thomas Grey", "license": "MIT", diff --git a/packages/typedoc-plugin-markdown/src/app/application.ts b/packages/typedoc-plugin-markdown/src/app/application.ts index 9aab428e4..3806c2535 100644 --- a/packages/typedoc-plugin-markdown/src/app/application.ts +++ b/packages/typedoc-plugin-markdown/src/app/application.ts @@ -4,14 +4,12 @@ import { Application, EventHooks, Options, Renderer } from 'typedoc'; import { MarkdownRendererHooks } from './renderer/markdown-renderer-hooks'; /** - * An extended typing of TypeDoc's Application instance. - * - * This is essentially a copy of the main class with the `renderer` property overridden to the custom {@link MarkdownRenderer}. + * This interface is essentially an extended typing of TypeDoc's {@linkcode typedoc!Application Application} instance. * * ## Usage * * ```ts - * import {MarkdownApplication} from 'typedoc-plugin-markdown'; + * import { MarkdownApplication } from 'typedoc-plugin-markdown'; * * export function load(app: MarkdownApplication) { * ... @@ -21,13 +19,14 @@ import { MarkdownRendererHooks } from './renderer/markdown-renderer-hooks'; * @category Application */ export interface MarkdownApplication extends Application { + /** + * Re-types the `renderer` instance to {@linkcode MarkdownRenderer }. + */ renderer: MarkdownRenderer; } /** - * An extended typing of TypeDoc's Renderer class. - * - * Includes updated typings for hooks and async jobs. + * An extended typing of TypeDoc's {@linkcode typedoc!Renderer Renderer} class that includes updated typings for hooks and async jobs. * * ## Usage * @@ -40,12 +39,12 @@ export interface MarkdownApplication extends Application { * 'page.begin', () => '> This is some markdown at the top of the page', * ); * - * app.renderer.preRenderAsyncJobs.push(async (event) => { - * await doSomethingAsync(event); + * app.renderer.preRenderAsyncJobs.push(async (output: MarkdownRendererEvent) => { + * await doSomethingAsync(output); * }); - * app.renderer.postRenderAsyncJobs.push(async (event) => { - * await doSomethingAsync(event); + * app.renderer.postRenderAsyncJobs.push(async (output: MarkdownRendererEvent)) => { + * await doSomethingAsync(output); * }); * * } @@ -54,6 +53,9 @@ export interface MarkdownApplication extends Application { * @category Application */ export interface MarkdownRenderer extends Renderer { + /** + * Replaces the event hooks typings the {@linkcode MarkdownRendererHooks} used by the plugin. + */ markdownHooks: EventHooks; /** @internal */ packagesMeta: Record; @@ -62,6 +64,12 @@ export interface MarkdownRenderer extends Renderer { name: string, theme: new (renderer: MarkdownRenderer) => MarkdownTheme, ) => void; + /** + * Re-types the returned argument argument to {@linkcode MarkdownRendererEvent}. + */ preRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise>; + /** + * Re-types the returned argument argument to {@linkcode MarkdownRendererEvent}. + */ postRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise>; } diff --git a/packages/typedoc-plugin-markdown/src/app/events/markdown-page-event.ts b/packages/typedoc-plugin-markdown/src/app/events/markdown-page-event.ts index bbe9e2b4e..79cd9564f 100644 --- a/packages/typedoc-plugin-markdown/src/app/events/markdown-page-event.ts +++ b/packages/typedoc-plugin-markdown/src/app/events/markdown-page-event.ts @@ -19,29 +19,30 @@ export class MarkdownPageEvent< /** @ignore **/ Model = Reflection, > extends Event { /** - * The project the renderer is currently processing. + * The {@linkcode typedoc!ProjectReflection ProjectReflection} instance the renderer is currently processing. */ project!: ProjectReflection; /** - * The model that should be rendered on this page. + * The model that that is being rendered on this page. + * Either a {@linkcode typedoc!DeclarationReflection DeclarationReflection} or {@linkcode typedoc!ProjectReflection ProjectReflection}. */ readonly model: Model; /** - * The final markdown content of this page. + * The final markdown `string` content of the page. * * Should be rendered by layout templates and can be modified by plugins. */ contents?: string; /** - * The url this page will be located at. + * The url `string` of the page. */ url!: string; /** - * The filename the page will be written to. + * The complete `string` filename where the file will be written.. */ filename!: string; diff --git a/packages/typedoc-plugin-markdown/src/app/internationalization/locales/en.ts b/packages/typedoc-plugin-markdown/src/app/internationalization/locales/en.ts new file mode 100644 index 000000000..4b357b18f --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/app/internationalization/locales/en.ts @@ -0,0 +1,16 @@ +export const translatable = { + theme_default_value: 'Default value', + theme_default_type: 'Default type', + theme_description: 'Description', + theme_event: 'Event', + theme_extends: 'Extends', + theme_extended_by: 'Extended by', + theme_member: 'Member', + theme_member_plural: 'Members', + theme_modifier: 'Modifier', + theme_name: 'Name', + theme_packages: 'Packages', + theme_type: 'Type', + theme_value: 'Value', + theme_version: 'Version', +}; diff --git a/packages/typedoc-plugin-markdown/src/app/internationalization/locales/ko.ts b/packages/typedoc-plugin-markdown/src/app/internationalization/locales/ko.ts new file mode 100644 index 000000000..b116761dc --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/app/internationalization/locales/ko.ts @@ -0,0 +1,18 @@ +import { TranslatableStrings } from '../translatable-types'; + +export const translatable: Partial = { + theme_default_value: '기본 값', + theme_default_type: '기본 유형', + theme_description: '설명', + theme_event: '이벤트', + theme_extends: '확장', + theme_extended_by: '에 의해 확장됨', + theme_member: '멤버', + theme_member_plural: '멤버들', + theme_modifier: '수정자', + theme_name: '이름', + theme_packages: '패키지', + theme_type: '유형', + theme_value: '값', + theme_version: '버전', +}; diff --git a/packages/typedoc-plugin-markdown/src/app/internationalization/translatable-types.ts b/packages/typedoc-plugin-markdown/src/app/internationalization/translatable-types.ts new file mode 100644 index 000000000..08578f0ec --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/app/internationalization/translatable-types.ts @@ -0,0 +1,18 @@ +// THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY. + +export interface TranslatableStrings { + theme_default_value: string; + theme_default_type: string; + theme_description: string; + theme_event: string; + theme_extends: string; + theme_extended_by: string; + theme_member: string; + theme_member_plural: string; + theme_modifier: string; + theme_name: string; + theme_packages: string; + theme_type: string; + theme_value: string; + theme_version: string; +} diff --git a/packages/typedoc-plugin-markdown/src/app/internationalization/translatable.ts b/packages/typedoc-plugin-markdown/src/app/internationalization/translatable.ts new file mode 100644 index 000000000..ae48144b0 --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/app/internationalization/translatable.ts @@ -0,0 +1,22 @@ +import { Application } from 'typedoc'; +import * as en from './locales/en'; +import * as ko from './locales/ko'; + +/** + * Returns subset of translatable strings for the plugin. + * + * These will then be merged with the main set of TypeDoc string. + */ +export function getTranslatable(app: Application) { + const LOCALES = { + en: en.translatable, + ko: ko.translatable, + }; + return { + ...LOCALES['en'], + ...(app.lang !== 'en' && Object.keys(LOCALES).includes(app.lang) + ? { ...LOCALES[app.lang] } + : {}), + ...app.options.getValue('locales')[app.lang], + }; +} diff --git a/packages/typedoc-plugin-markdown/src/app/renderer/overrides.ts b/packages/typedoc-plugin-markdown/src/app/renderer/overrides.ts index 56528f0e8..e8cc0ca1c 100644 --- a/packages/typedoc-plugin-markdown/src/app/renderer/overrides.ts +++ b/packages/typedoc-plugin-markdown/src/app/renderer/overrides.ts @@ -86,7 +86,7 @@ export async function render( this.preRenderAsyncJobs = []; - if (!output.isDefaultPrevented) { + if (!output.isDefaultPrevented()) { this.application.logger.verbose( `There are ${output.urls?.length} pages to write.`, ); @@ -103,7 +103,7 @@ export async function render( this.trigger(MarkdownPageEvent.BEGIN, page); - if (page.isDefaultPrevented) { + if (page.isDefaultPrevented()) { return false; } @@ -115,7 +115,7 @@ export async function render( this.trigger(MarkdownPageEvent.END, page); - if (page.isDefaultPrevented) { + if (page.isDefaultPrevented()) { return false; } diff --git a/packages/typedoc-plugin-markdown/src/app/translatable.ts b/packages/typedoc-plugin-markdown/src/app/translatable.ts deleted file mode 100644 index 86f481f02..000000000 --- a/packages/typedoc-plugin-markdown/src/app/translatable.ts +++ /dev/null @@ -1,73 +0,0 @@ -import { Application } from 'typedoc'; - -export function getTranslatable(app: Application) { - // read text content mappings for backward compatibility - const textContentMappings = app.options.getValue('textContentMappings'); - return { ...translatable, ...serializeTextContent(textContentMappings) }; -} - -export const translatable = { - // header - theme_header_title: '{0} {1}', // {projectName} {version}, - theme_header_docs: 'Docs', // displayed in the header when readme is resolved - - // breadcrumbs - theme_breadcrumbs_home: '{0} {1}', // {projectName} {version}, - - // titles - theme_title_index_page: '{0} {1}', // {projectName} {version}, - theme_title_member_page: '{0}: {1}', // {kind}: {name} - theme_title_module_page: '{0}', // {name}, - - // footer - theme_footer_text: '', - - // generic labels - theme_api_index: 'API Index', - theme_default_value: 'Default Value', - theme_description: 'Description', - theme_event: 'Event', - theme_extends: 'Extends', - theme_extended_by: 'Extended By', - theme_flags: 'Flags', - theme_globals: 'Globals', - theme_member: 'Member', - theme_member_plural: 'Members', - theme_modifier: 'Modifier', - theme_name: 'Name', - theme_packages: 'Packages', - theme_source: 'Source', - theme_type: 'Type', - theme_value: 'Value', - theme_version: 'Version', -}; - -/** - * textContentMappings is now deprecated. - * - * This method maps textContentMappings to translatable object to avoid a breaking options change. - * - * This method will be removed once textContentMappings is removed from options declaration. - * - */ -function serializeTextContent(textContentMappings: any) { - const output: { [key: string]: string } = {}; - for (const [key, value] of Object.entries(textContentMappings)) { - const newKey = 'theme_' + camelToSnakeCase(key.replace(/\./g, '_')); - let newValue = (value as any) - .replace(/{version}/g, '{1}') - .replace(/{kind}/g, '{0}') - .replace(/{projectName}/g, '{0}'); - if (newKey === 'theme_title_member_page') { - newValue = newValue.replace(/{name}/g, '{1}'); - } else { - newValue = newValue.replace(/{name}/g, '{0}'); - } - output[newKey] = newValue; - } - return output; -} - -function camelToSnakeCase(str: string) { - return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`); -} diff --git a/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts b/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts index d619d7734..e554b6855 100644 --- a/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts +++ b/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts @@ -1,6 +1,5 @@ // THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY. import { ManuallyValidatedOption } from 'typedoc'; -import { TextContentMappings } from '../options/option-types'; declare module 'typedoc' { export interface TypeDocOptionMap { anchorPrefix: string; @@ -17,9 +16,7 @@ declare module 'typedoc' { hideGroupHeadings: boolean; hidePageHeader: boolean; hidePageTitle: boolean; - indexFormat: 'list' | 'table' | 'htmlTable'; - inlineDocuments: boolean; - leftAlignTableHeaders: boolean; + indexFormat: 'list' | 'table'; membersWithOwnFile: ( | 'Enum' | 'Variable' @@ -40,14 +37,23 @@ declare module 'typedoc' { propertiesFormat: 'list' | 'table' | 'htmlTable'; publicPath: string; sanitizeComments: boolean; - tableColumnVisibility: { + tableColumnSettings: { hideDefaults: boolean; hideInherited: boolean; hideModifiers: boolean; hideOverrides: boolean; hideSources: boolean; + hideValues: boolean; + leftAlignHeaders: boolean; }; - textContentMappings: ManuallyValidatedOption>; + textContentMappings: ManuallyValidatedOption<{ + 'header.title': string; + 'header.docs': string; + 'breadcrumbs.home': string; + 'title.indexPage': string; + 'title.memberPage': string; + 'footer.text': string; + }>; typeDeclarationFormat: 'list' | 'table' | 'htmlTable'; useCodeBlocks: boolean; useHTMLAnchors: boolean; @@ -56,27 +62,17 @@ declare module 'typedoc' { // eslint-disable-next-line @typescript-eslint/no-namespace export namespace Internationalization { export interface TranslatableStrings { - theme_header_title: [string, string]; - theme_header_docs: []; - theme_breadcrumbs_home: [string, string]; - theme_title_index_page: [string, string]; - theme_title_member_page: [string, string]; - theme_title_module_page: [string]; - theme_footer_text: []; - theme_api_index: []; theme_default_value: []; + theme_default_type: []; theme_description: []; theme_event: []; theme_extends: []; theme_extended_by: []; - theme_flags: []; - theme_globals: []; theme_member: []; theme_member_plural: []; theme_modifier: []; theme_name: []; theme_packages: []; - theme_source: []; theme_type: []; theme_value: []; theme_version: []; diff --git a/packages/typedoc-plugin-markdown/src/index.ts b/packages/typedoc-plugin-markdown/src/index.ts index c156e4cf9..fe1215f3c 100644 --- a/packages/typedoc-plugin-markdown/src/index.ts +++ b/packages/typedoc-plugin-markdown/src/index.ts @@ -15,6 +15,7 @@ import { Renderer, Theme, } from 'typedoc'; +import { getTranslatable } from './app/internationalization/translatable'; /** * The function that is called by TypeDoc to bootstrap the plugin. https://typedoc.org/guides/development/#plugins. @@ -42,16 +43,9 @@ export function load(app: Application) { } as DeclarationOption); }); - /** - * ========================================= - * 2. Extend locale with plugin translations - * ========================================= - */ - //app.internationalization.addTranslations('en', getTranslatable(app)); - /** * ================================================= - * 3. Intercept and modify some TypeDoc core methods + * 2. Intercept and modify some TypeDoc core methods * ================================================= * * Currently the TypeDoc {@link Renderer} class is quite coupled to the HTML theme so we override a couple of core methods. @@ -90,7 +84,20 @@ export function load(app: Application) { /** * ============================ - * 3. Apply any other behaviour + * 3. Configure localization + * ============================ + */ + app.converter.on(Converter.EVENT_BEGIN, () => { + app.internationalization.addTranslations( + app.options.getValue('lang'), + { ...getTranslatable(app) /*...app.options.getValue('locales')*/ }, + true, + ); + }); + + /** + * ============================ + * 4. Apply any other behaviour * ============================ */ diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts index 614673149..d34f59194 100644 --- a/packages/typedoc-plugin-markdown/src/options/declarations.ts +++ b/packages/typedoc-plugin-markdown/src/options/declarations.ts @@ -1,8 +1,10 @@ import { DeclarationOption, ParameterType } from 'typedoc'; import { - FormatStyle, - MembersWithOwnFile, + ALLOWED_OWN_FILE_MEMBERS, + IndexFormat, OutputFileStrategy, + ReflectionFormat, + TEXT_CONTENT_MAPPINGS, } from './option-maps'; /** @@ -65,7 +67,7 @@ export const membersWithOwnFile: Partial = { help: 'Determines which members are exported to their own file when `outputFileStrategy` equals `members`.', type: ParameterType.Array, validate(values) { - const validValues = MembersWithOwnFile; + const validValues = ALLOWED_OWN_FILE_MEMBERS; for (const kind of values) { if (!validValues.includes(kind)) { throw new Error( @@ -76,7 +78,7 @@ export const membersWithOwnFile: Partial = { } } }, - defaultValue: MembersWithOwnFile, + defaultValue: ALLOWED_OWN_FILE_MEMBERS, }; /** @@ -209,12 +211,15 @@ export const excludeScopesInPaths: Partial = { }; /** - * By default when a readme file is resolved, a separate readme page is created. This option appends the index page to the readme so only a single root page is generated. + * By default when a readme file is resolved, a separate readme page is created. + * This option appends the index page to the readme so only a single root page is generated. + * + * You can additionally configure the generated title with `"textContentMappings": { "title.indexPage" : "My API"}`. + * See [`--textContentMappings`](/docs/options/utility-options#--textcontentmappings). * * This option has no effect when [`readme`](https://typedoc.org/options/input/#readme) is set to `"none"`. * * @category File - * */ export const mergeReadme: Partial = { help: 'Merges the resolved readme into the project index page.', @@ -222,19 +227,6 @@ export const mergeReadme: Partial = { defaultValue: false, }; -/** - * By default a documents indexes and separate documents pages are generated when using the `@document` tag. - * - * This option inlines the document into the page rather than generating a separate document page. - * - * @category File - */ -export const inlineDocuments: Partial = { - help: 'Inline documents in pages.', - type: ParameterType.Boolean, - defaultValue: false, -}; - /** * @category Display */ @@ -332,15 +324,15 @@ export const expandParameters: Partial = { * * - **"list"**: parameters are output as bullet points in a linear list, suitable for more detailed comments. * - **"table"**: parameters are output within a markdown table, condensed into a single paragraph. - * - **"htmlTable"**: parameters are output in an HTML table, enabling block elements to render in tabular format. + * - **"htmlTable"**: parameters are output in an HTML table, enabling block elements to render in tabular format * * @category Display */ export const parametersFormat: Partial = { help: 'Specify the render style of parameter and type parameter groups.', type: ParameterType.Map, - map: FormatStyle, - defaultValue: FormatStyle.List, + map: ReflectionFormat, + defaultValue: ReflectionFormat.List, }; /** @@ -355,8 +347,8 @@ export const parametersFormat: Partial = { export const propertiesFormat: Partial = { help: 'Specify the render style of property groups for interfaces and classes.', type: ParameterType.Map, - map: FormatStyle, - defaultValue: FormatStyle.List, + map: ReflectionFormat, + defaultValue: ReflectionFormat.List, }; /** @@ -371,8 +363,8 @@ export const propertiesFormat: Partial = { export const enumMembersFormat: Partial = { help: 'Specify the render style of enumeration members.', type: ParameterType.Map, - map: FormatStyle, - defaultValue: FormatStyle.List, + map: ReflectionFormat, + defaultValue: ReflectionFormat.List, }; /** @@ -387,32 +379,37 @@ export const enumMembersFormat: Partial = { export const typeDeclarationFormat: Partial = { help: 'Specify the render style for type declaration members.', type: ParameterType.Map, - map: FormatStyle, - defaultValue: FormatStyle.List, + map: ReflectionFormat, + defaultValue: ReflectionFormat.List, }; /** - * This option renders index items either as a simple list or in a table with a description column exposing the comment summary. + * This option renders index items either as a simple unordered list or in a table. + * + * When table style is selected the following will be the behaviour: * - * For a packages index page (when `--entryPointStrategy` equals `packages`), the package.json description will be displayed with an additional "Version" column (when `--includeVersion` equals true). + * - For a **members index**, a description column will be added to the table with the first paragraph of the comment summary. + * - For a **packages index**, (when `--entryPointStrategy` equals `packages`), the package.json description will be displayed with an additional "Version" column (when `--includeVersion` equals true). + * - For a **documents index** a description column will be added to the table printing the `description` frontmatter if present. * * @category Display */ export const indexFormat: Partial = { help: 'Specify the render format for index items.', type: ParameterType.Map, - map: FormatStyle, - defaultValue: FormatStyle.List, + map: IndexFormat, + defaultValue: ReflectionFormat.List, }; /** - * By default, all available data for symbols are displayed in table columns. + * By default, all available data for symbols are displayed in table columns. For some reflections this can result in several columns. * * This option allows you to control the visibility of columns, prioritizing readability over displaying complete data. + * In addition you can control the alignment of the header text. * * @category Display */ -export const tableColumnVisibility: Partial = { +export const tableColumnSettings: Partial = { help: 'Control header alignment and column visibility in tables.', type: ParameterType.Flags, defaults: { @@ -421,22 +418,11 @@ export const tableColumnVisibility: Partial = { hideModifiers: false, hideOverrides: false, hideSources: false, + hideValues: false, + leftAlignHeaders: false, }, }; -/** - * By default table alignment is not specified which means the table headings will typically be centred. - * - * This options can be used to specify left alignment for table headings. - * - * @category Display - */ -export const leftAlignTableHeaders: Partial = { - help: 'Left aligns items in table headers', - type: ParameterType.Boolean, - defaultValue: false, -}; - /** * If undefined all urls will be relative. * @@ -553,25 +539,29 @@ export const navigationModel: Partial = { /** * - * This option enables changing static text rendered to the documentation. + * Defines placeholder text in main template that can be customized. Includes the main page header and breadcrumbs (if displayed), + * page titles and page footer. * - * @deprecated + * Default values within curly braces {} indicates a placeholder of dynamic text. + * + * - The `{projectName}` placeholder writes project's name . + * - The `{kind}` writes the reflection kind of the page. + * - The `{version}` placeholder writes package version (if includeVersion is `true`). * - * This option has been deprecated in favour of TypeDoc's 0.26 localization feature. + * If you are looking for general localization support please see [localization](). * * @category Utility */ export const textContentMappings: Partial = { - help: '@deprecated Provides a mechanism to change the content of text used in documentation.', - type: ParameterType.Mixed, - defaultValue: {}, + help: 'Change specific text placeholders in the template.', + type: ParameterType.Object, + defaultValue: TEXT_CONTENT_MAPPINGS, validate(value) { if (!value || typeof value !== 'object') { throw new Error( '[typedoc-plugin-markdown] textContentMappings must be an object.', ); } - for (const val of Object.values(value)) { if (typeof val !== 'string') { throw new Error( diff --git a/packages/typedoc-plugin-markdown/src/options/option-maps.ts b/packages/typedoc-plugin-markdown/src/options/option-maps.ts index f68976c3f..9d59ec0f8 100644 --- a/packages/typedoc-plugin-markdown/src/options/option-maps.ts +++ b/packages/typedoc-plugin-markdown/src/options/option-maps.ts @@ -8,15 +8,23 @@ export const OutputFileStrategy = { export type OutputFileStrategy = (typeof OutputFileStrategy)[keyof typeof OutputFileStrategy]; -export const FormatStyle = { +export const ReflectionFormat = { List: 'list', Table: 'table', HtmlTable: 'htmlTable', } as const; -export type FormatStyle = (typeof FormatStyle)[keyof typeof FormatStyle]; +export type ReflectionFormat = + (typeof ReflectionFormat)[keyof typeof ReflectionFormat]; -export const MembersWithOwnFile = [ +export const IndexFormat = { + List: 'list', + Table: 'table', +} as const; + +export type IndexFormat = (typeof IndexFormat)[keyof typeof IndexFormat]; + +export const ALLOWED_OWN_FILE_MEMBERS = [ ReflectionKind[ReflectionKind.Enum], ReflectionKind[ReflectionKind.Variable], ReflectionKind[ReflectionKind.Function], @@ -24,3 +32,12 @@ export const MembersWithOwnFile = [ ReflectionKind[ReflectionKind.Interface], ReflectionKind[ReflectionKind.TypeAlias], ]; + +export const TEXT_CONTENT_MAPPINGS = { + 'header.title': '{projectName} {version}', + 'header.docs': 'Docs', + 'breadcrumbs.home': '{projectName} {version}', + 'title.indexPage': '{projectName} {version}', + 'title.memberPage': '{kind}: {name}', + 'footer.text': '', +}; diff --git a/packages/typedoc-plugin-markdown/src/options/option-types.ts b/packages/typedoc-plugin-markdown/src/options/option-types.ts index d73ebbdd7..a64b59fa8 100644 --- a/packages/typedoc-plugin-markdown/src/options/option-types.ts +++ b/packages/typedoc-plugin-markdown/src/options/option-types.ts @@ -79,17 +79,7 @@ export interface PluginOptions { /** * Specify the render format for index items. */ - indexFormat: 'list' | 'table' | 'htmlTable'; - - /** - * Inline documents in pages. - */ - inlineDocuments: boolean; - - /** - * Left aligns items in table headers - */ - leftAlignTableHeaders: boolean; + indexFormat: 'list' | 'table'; /** * Determines which members are exported to their own file when `outputFileStrategy` equals `members`. @@ -150,18 +140,27 @@ export interface PluginOptions { /** * Control header alignment and column visibility in tables. */ - tableColumnVisibility: { + tableColumnSettings: { hideDefaults: boolean; hideInherited: boolean; hideModifiers: boolean; hideOverrides: boolean; hideSources: boolean; + hideValues: boolean; + leftAlignHeaders: boolean; }; /** - * @deprecated Provides a mechanism to change the content of text used in documentation. + * Change specific text placeholders in the template. */ - textContentMappings: Partial; + textContentMappings: { + 'header.title': string; + 'header.docs': string; + 'breadcrumbs.home': string; + 'title.indexPage': string; + 'title.memberPage': string; + 'footer.text': string; + }; /** * Specify the render style for type declaration members. @@ -178,10 +177,3 @@ export interface PluginOptions { */ useHTMLAnchors: boolean; } - -/** - * Describes the keys available to replace static text. - * - * @category Options - */ -export interface TextContentMappings {} diff --git a/packages/typedoc-plugin-markdown/src/public-api.ts b/packages/typedoc-plugin-markdown/src/public-api.ts index 34f0acf9b..963c4d3ef 100644 --- a/packages/typedoc-plugin-markdown/src/public-api.ts +++ b/packages/typedoc-plugin-markdown/src/public-api.ts @@ -1,5 +1,5 @@ /** - * The public API of typedoc-plugin-markdown exposes some classes and types that can be used to customize the output of the plugin. Please note this only covers the API relevant to this plugin and not cover the entire [TypeDoc API](https://typedoc.org/api/). + * The public API of typedoc-plugin-markdown exposes some classes and types that can be used to customize the output of the plugin. If you are interested in the TypeDoc API please visit [https://typedoc.org](https://typedoc.org/api/). * * The APIs are typically consumed by writing [local plugins](/docs/customizing-output#local-plugins). * diff --git a/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts b/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts index acb60b235..311e37bd9 100644 --- a/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts +++ b/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts @@ -89,7 +89,7 @@ export class NavigationBuilder { ) { children.push({ title: - this.theme.application.internationalization.proxy.theme_globals(), + this.theme.application.internationalization.proxy.kind_plural_module(), path: projectChild.url, kind: projectChild.kind, }); diff --git a/packages/typedoc-plugin-markdown/src/theme/core/url-builder.ts b/packages/typedoc-plugin-markdown/src/theme/core/url-builder.ts index ab880ca40..09f9454c4 100644 --- a/packages/typedoc-plugin-markdown/src/theme/core/url-builder.ts +++ b/packages/typedoc-plugin-markdown/src/theme/core/url-builder.ts @@ -36,7 +36,6 @@ export class UrlBuilder { private fileExtension: string; private ignoreScopes: boolean; private entryFileName: string; - private writeDocuments: boolean; private isPackages: boolean; private flattenOutputFiles: boolean; private urls: UrlMapping[] = []; @@ -54,7 +53,6 @@ export class UrlBuilder { this.fileExtension = this.options.getValue('fileExtension'); this.ignoreScopes = this.options.getValue('excludeScopesInPaths'); - this.writeDocuments = !this.options.getValue('inlineDocuments'); this.entryFileName = getFileNameWithExtension( this.options.getValue('entryFileName'), @@ -145,10 +143,7 @@ export class UrlBuilder { ) { project.groups?.forEach((projectGroup) => { projectGroup.children?.forEach((projectGroupChild) => { - if ( - this.writeDocuments && - projectGroupChild instanceof DocumentReflection - ) { + if (projectGroupChild instanceof DocumentReflection) { this.buildUrlsForDocuments(projectGroupChild); } if (projectGroupChild instanceof DeclarationReflection) { @@ -309,10 +304,6 @@ export class UrlBuilder { reflection: DeclarationReflection, urlOptions: UrlOption, ) { - if (reflection.kind === ReflectionKind.Document && !this.writeDocuments) { - return; - } - const mapping: TemplateMapping = this.theme.getTemplateMapping( reflection.kind, urlOptions.outputFileStrategy, @@ -343,10 +334,7 @@ export class UrlBuilder { urlMapping.url !== url, ); - if ( - duplicateUrls.length > 0 && - reflection.kind !== ReflectionKind.Document - ) { + if (duplicateUrls.length > 0) { const urlParts = url.split('.'); urlParts[urlParts.length - 2] += `-${duplicateUrls.length}`; url = urlParts.join('.'); @@ -492,7 +480,7 @@ export class UrlBuilder { } if (reflection.parent) { reflection.traverse((child) => { - if (this.writeDocuments && child instanceof DocumentReflection) { + if (child instanceof DocumentReflection) { this.buildUrlsForDocuments(child); } if (child instanceof DeclarationReflection) { @@ -556,7 +544,8 @@ export class UrlBuilder { if (!htmlTableAnchors) { if ( (reflection.kind === ReflectionKind.Property && - this.options.getValue('propertiesFormat') === 'table') || + this.options.getValue('propertiesFormat').toLowerCase() === + 'table') || (reflection.kind === ReflectionKind.EnumMember && this.options.getValue('enumMembersFormat') === 'table') ) { diff --git a/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts b/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts index 65923bf14..79ac5d29c 100644 --- a/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts +++ b/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts @@ -1,6 +1,4 @@ -import { MarkdownRenderer } from '@plugin/app/application'; import { MarkdownPageEvent } from '@plugin/app/events'; -import { getTranslatable } from '@plugin/app/translatable'; import { formatMarkdown } from '@plugin/libs/utils'; import { OutputFileStrategy } from '@plugin/options'; import { RenderTemplate } from '@plugin/theme'; @@ -40,23 +38,6 @@ import { MarkdownThemeContext } from './markdown-themecontext'; * @category Theme */ export class MarkdownTheme extends Theme { - /** - * The text content mappings for the theme. This is a combination of the default mappings and any mappings provided in the plugin options. - * - * @internal - */ - - /** - * @ignore - */ - constructor(renderer: MarkdownRenderer) { - super(renderer); - this.application.internationalization.addTranslations( - 'en', - getTranslatable(this.application), - ); - } - /** * Renders a template and page model to a string. * diff --git a/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts b/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts index 1f2835ead..30a53fe84 100644 --- a/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts +++ b/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts @@ -11,7 +11,7 @@ import { Internationalization, Options, Reflection } from 'typedoc'; * * It is heavily influenced by the equivalent [DefaultThemeRenderContext](https://typedoc.org/api/classes/DefaultThemeRenderContext.html) from the default theme. * - * This class can be used to customize the theme output by extending the class and overriding the [templates](#templates), [partials](#partials) and [helpers](#helpers). + * This class can be used to customize the theme output by extending the class and overriding the templates, partials and helpers. * * ## Usage * @@ -94,11 +94,11 @@ export class MarkdownThemeContext { * * Partials are categorised by their use: * - * - [Page Partials](#page-partials): Partials that render core page elements such as header and breadcrumbs. - * - [Container Partials](#container-partials): Partials that are used to render reflection groups and categories. - * - [Member Partials](#member-partials): Partials that render specific parts of reflections. - * - [Comment Partials](#comment-partials): Partials that render comments. - * - [Type Partials](#type-partials): Partials that render specific TypeDoc model types. + * - Page Partials: Partials that render core page elements such as header and breadcrumbs. + * - Container Partials: Partials that are used to render reflection groups and categories. + * - Member Partials: Partials that render specific parts of reflections. + * - Comment Partials: Partials that render comments. + * - Type Partials: Partials that render specific TypeDoc model types. * * @group Resources */ diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-comment-parts.ts b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-comment-parts.ts new file mode 100644 index 000000000..7f63e1f94 --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-comment-parts.ts @@ -0,0 +1,70 @@ +import { link } from '@plugin/libs/markdown'; +import { MarkdownThemeContext } from '@plugin/theme'; +import * as fs from 'fs'; +import { CommentDisplayPart, InlineTagDisplayPart } from 'typedoc'; + +export function getCommentParts( + this: MarkdownThemeContext, + model: CommentDisplayPart[], +): string { + const md: string[] = []; + for (const part of model) { + switch (part.kind) { + case 'text': + md.push(part.text); + break; + case 'code': + md.push(part.text); + break; + case 'inline-tag': + switch (part.tag) { + case '@label': + case '@inheritdoc': + break; + case '@link': + case '@linkcode': + case '@linkplain': { + if (part.target) { + const url = getUrl(part); + const wrap = part.tag === '@linkcode' ? '`' : ''; + md.push( + url + ? `${link(`${wrap}${part.text}${wrap}`, this.getRelativeUrl(url))}` + : part.text, + ); + } else { + md.push(part.text); + } + break; + } + default: + md.push(`{${part.tag} ${part.text}}`); + break; + } + break; + default: + md.push(''); + } + } + return md.join(''); +} + +function getUrl(part: InlineTagDisplayPart) { + if ((part.target as any).url) { + return (part.target as any).url; + } + + if ((part.target as any)?.parent?.url) { + return (part.target as any)?.parent?.url; + } + + return typeof part.target === 'string' ? part.target : ''; +} + +export function isFile(file: string) { + try { + return fs.statSync(file).isFile(); + } catch { + return false; + } +} diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-group-index-table.ts b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-group-index-table.ts index 4b2cd83de..640307a55 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-group-index-table.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-group-index-table.ts @@ -11,7 +11,9 @@ export function getGroupIndexTable( this: MarkdownThemeContext, children: DeclarationReflection[] | DocumentReflection[], ) { - const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + const leftAlignHeadings = this.options.getValue( + 'tableColumnSettings', + ).leftAlignHeaders; const headers = [ this.options.getValue('excludeGroups') || this.options.getValue('hideGroupHeadings') diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-project-name.ts b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-project-name.ts new file mode 100644 index 000000000..0d4174575 --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-project-name.ts @@ -0,0 +1,16 @@ +import { MarkdownPageEvent } from 'public-api'; +import { Reflection } from 'typedoc'; + +export function getProjectName( + stringWithPlaceholders: string, + page: MarkdownPageEvent, +) { + return stringWithPlaceholders + .replace('{projectName}', page.project.name) + .replace( + '{version}', + page.project.packageVersion ? `v${page.project.packageVersion}` : '', + ) + .replace(/\s+/g, ' ') + .trim(); +} diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionFlags.ts b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-reflection-flags.ts similarity index 53% rename from packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionFlags.ts rename to packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-reflection-flags.ts index a9fd1d326..45209f6b5 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionFlags.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/get-reflection-flags.ts @@ -1,33 +1,24 @@ -import { backTicks } from '@plugin/libs/markdown'; import { camelToTitleCase } from '@plugin/libs/utils'; import { MarkdownThemeContext } from '@plugin/theme'; -import { Reflection } from 'typedoc'; +import { DeclarationReflection, SignatureReflection } from 'typedoc'; -/** - * Renders the flags of a reflection. - * - * @category Member Partials - */ -export function reflectionFlags( +export function getReflectionFlags( this: MarkdownThemeContext, - model: Reflection, -): string { + reflection: DeclarationReflection | SignatureReflection, +): string[] { const flagsNotRendered: `@${string}`[] = [ '@showCategories', '@showGroups', '@hideCategories', '@hideGroups', ]; - const flags: string[] = []; - - if (model.comment) { - for (const tag of model.comment.modifierTags) { + if (reflection.comment) { + for (const tag of reflection.comment.modifierTags) { if (!flagsNotRendered.includes(tag)) { flags.push(camelToTitleCase(tag.substring(1))); } } } - - return flags.map((item) => backTicks(item)).join(' '); + return flags; } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/helpers/use-table.format.ts b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/use-table.format.ts new file mode 100644 index 000000000..0a5c0a861 --- /dev/null +++ b/packages/typedoc-plugin-markdown/src/theme/resources/helpers/use-table.format.ts @@ -0,0 +1,24 @@ +import { MarkdownThemeContext } from 'public-api'; + +export function useTableFormat( + this: MarkdownThemeContext, + key: 'properties' | 'parameters' | 'enums' | 'typeDeclarations', +): boolean { + if (key === 'parameters') { + return isTable(this.options.getValue('parametersFormat')); + } + if (key === 'properties') { + return isTable(this.options.getValue('propertiesFormat')); + } + if (key === 'enums') { + return isTable(this.options.getValue('enumMembersFormat')); + } + if (key === 'typeDeclarations') { + return isTable(this.options.getValue('typeDeclarationFormat')); + } + return false; +} + +function isTable(key: string) { + return key.toLowerCase().includes('table'); +} diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/index.ts b/packages/typedoc-plugin-markdown/src/theme/resources/index.ts index 6b22c7732..a08de4124 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/index.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/index.ts @@ -60,9 +60,8 @@ import { memberTitle } from './partials/member.memberTitle'; import { memberWithGroups } from './partials/member.memberWithGroups'; import { parametersList } from './partials/member.parametersList'; import { parametersTable } from './partials/member.parametersTable'; -import { declarationsTable } from './partials/member.propertiesTable'; +import { propertiesTable } from './partials/member.propertiesTable'; import { referenceMember } from './partials/member.reference'; -import { reflectionFlags } from './partials/member.reflectionFlags'; import { reflectionIndex } from './partials/member.reflectionIndex'; import { signature } from './partials/member.signature'; import { signatureParameters } from './partials/member.signatureParameters'; @@ -102,6 +101,7 @@ import { typeOperatorType } from './partials/type.type-operator'; import { unionType } from './partials/type.union'; import { unknownType } from './partials/type.unknown'; +import { getCommentParts } from './helpers/get-comment-parts'; import { getDeclarationType } from './helpers/get-declaration-type'; import { getDescriptionForReflection } from './helpers/get-description-for-reflection'; import { getFlattenedDeclarations } from './helpers/get-flattened-declarations'; @@ -112,9 +112,12 @@ import { getHierarchyType } from './helpers/get-hierarchy-type'; import { getKeyword } from './helpers/get-keyword'; import { getModifier } from './helpers/get-modifier'; import { getParameterDefaultValue } from './helpers/get-parameter-default-value'; +import { getProjectName } from './helpers/get-project-name'; import { getPropertyDefaultValue } from './helpers/get-property-default-value'; +import { getReflectionFlags } from './helpers/get-reflection-flags'; import { getReturnType } from './helpers/get-return-type'; import { isGroupKind } from './helpers/is-group-kind'; +import { useTableFormat } from './helpers/use-table.format'; export const templates = (context: MarkdownThemeContext) => { return { @@ -300,22 +303,16 @@ There is no association list partial for properties as these are handled as a st * @category Member Partials * */ - declarationsTable: ( + propertiesTable: ( model: DeclarationReflection[], options?: { isEventProps: boolean } | undefined, - ) => declarationsTable.apply(context, [model, options]) as string, + ) => propertiesTable.apply(context, [model, options]) as string, /** * Renders an reference member. * @category Member Partials */ referenceMember: (model: ReferenceReflection) => referenceMember.apply(context, [model]) as string, - /** - * Renders the flags of a reflection. - * @category Member Partials - */ - reflectionFlags: (model: Reflection) => - reflectionFlags.apply(context, [model]) as string, /** * * @category Member Partials @@ -576,6 +573,8 @@ There is no association list partial for properties as these are handled as a st export const helpers = (context: MarkdownThemeContext) => { return { + getCommentParts: (model: CommentDisplayPart[]) => + getCommentParts.apply(context, [model]) as string, getDeclarationType: (model: DeclarationReflection) => getDeclarationType.apply(context, [model]) as SomeType | undefined, getDescriptionForReflection: (model: DeclarationReflection) => @@ -606,11 +605,22 @@ export const helpers = (context: MarkdownThemeContext) => { getModifier.apply(context, [model]) as string | null, getParameterDefaultValue: (model: ParameterReflection) => getParameterDefaultValue.apply(context, [model]) as string, + getProjectName: ( + stringWithPlaceholders: string, + page: MarkdownPageEvent, + ) => + getProjectName.apply(context, [stringWithPlaceholders, page]) as string, getPropertyDefaultValue: (model: DeclarationReflection) => getPropertyDefaultValue.apply(context, [model]) as string | null, + getReflectionFlags: ( + reflection: DeclarationReflection | SignatureReflection, + ) => getReflectionFlags.apply(context, [reflection]) as string[], getReturnType: (model?: SomeType | undefined) => getReturnType.apply(context, [model]) as string, isGroupKind: (model: DeclarationReflection | SignatureReflection) => isGroupKind.apply(context, [model]) as boolean, + useTableFormat: ( + key: 'properties' | 'parameters' | 'enums' | 'typeDeclarations', + ) => useTableFormat.apply(context, [key]) as boolean, }; }; diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts index e39846c92..4218f77e0 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts @@ -28,7 +28,7 @@ export function comment( const md: string[] = []; if (opts.showSummary && model.summary?.length > 0) { - md.push(this.partials.commentParts(model.summary)); + md.push(this.helpers.getCommentParts(model.summary)); } if (opts.showTags && model.blockTags?.length) { diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts index 24c2a2076..9da01007a 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.groups.ts @@ -26,7 +26,8 @@ export function groups( return groupTitle; }; - groupsWithChildren?.forEach((group, index: number) => { + groupsWithChildren?.forEach((group) => { + const isEventProps = getGroupTitle(group.title) === 'Events'; if (group.categories) { md.push(heading(options.headingLevel, getGroupTitle(group.title))); if (group.description) { @@ -50,28 +51,17 @@ export function groups( if (group.description) { md.push(this.partials.commentParts(group.description)); } - if ( - isPropertiesGroup && - this.options - .getValue('propertiesFormat') - .toLowerCase() - .includes('table') - ) { + + if (isPropertiesGroup && this.helpers.useTableFormat('properties')) { md.push( - this.partials.declarationsTable( + this.partials.propertiesTable( group.children as DeclarationReflection[], { - isEventProps: getGroupTitle(group.title) === 'Events', + isEventProps, }, ), ); - } else if ( - isEnumGroup && - this.options - .getValue('enumMembersFormat') - .toLowerCase() - .includes('table') - ) { + } else if (isEnumGroup && this.helpers.useTableFormat('enums')) { md.push( this.partials.enumMembersTable( group.children as DeclarationReflection[], diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts index 429fe38d4..7fb99d01d 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.accessor.ts @@ -50,7 +50,7 @@ export function accessor( this.internationalization.kindPluralString(ReflectionKind.Parameter), ), ); - if (this.options.getValue('parametersFormat') === 'table') { + if (this.helpers.useTableFormat('parameters')) { md.push(this.partials.parametersTable(model.setSignature.parameters)); } else { md.push(this.partials.parametersList(model.setSignature.parameters)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts index f85f29b7f..296ed1299 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.declaration.ts @@ -1,4 +1,4 @@ -import { heading } from '@plugin/libs/markdown'; +import { backTicks, heading } from '@plugin/libs/markdown'; import { MarkdownThemeContext } from '@plugin/theme'; import { DeclarationReflection, @@ -31,7 +31,12 @@ export function declaration( ...options, }; - md.push(this.partials.reflectionFlags(model)); + md.push( + this.helpers + .getReflectionFlags(model) + .map((item) => backTicks(item)) + .join(' '), + ); md.push(this.partials.declarationTitle(model)); @@ -105,9 +110,7 @@ export function declaration( ), ), ); - if ( - this.options.getValue('parametersFormat').toLowerCase().includes('table') - ) { + if (this.helpers.useTableFormat('parameters')) { md.push(this.partials.typeParametersTable(model.typeParameters)); } else { md.push(this.partials.typeParametersList(model.typeParameters)); @@ -136,7 +139,7 @@ export function declaration( if (typeDeclaration?.children?.length) { const useHeading = model.kind !== ReflectionKind.Property || - this.options.getValue('propertiesFormat') == 'table'; + this.helpers.useTableFormat('properties'); if (!opts.nested && typeDeclaration?.children?.length) { if (useHeading) { md.push( diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.documents.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.documents.ts index 5cd47f615..6dd04b9e7 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.documents.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.documents.ts @@ -22,17 +22,9 @@ export function documents( if (docGroups?.length) { docGroups.forEach((reflectionGroup) => { md.push(heading(options.headingLevel, reflectionGroup.title)); - if (this.options.getValue('inlineDocuments')) { - reflectionGroup.children.forEach((child) => { - md.push( - this.partials.commentParts((child as DocumentReflection).content), - ); - }); - } else { - docGroups.forEach((reflectionGroup) => { - md.push(this.helpers.getGroupIndex(reflectionGroup)); - }); - } + docGroups.forEach((reflectionGroup) => { + md.push(this.helpers.getGroupIndex(reflectionGroup)); + }); }); } return md.join('\n\n'); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts index 620e21500..e3d23df71 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.enumMembersTable.ts @@ -12,8 +12,8 @@ export function enumMembersTable( this: MarkdownThemeContext, model: DeclarationReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); - const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + const tableColumnsOptions = this.options.getValue('tableColumnSettings'); + const leftAlignHeadings = tableColumnsOptions.leftAlignHeaders; const comments = model.map((param) => !!param.comment?.hasVisibleComponent()); const hasComments = comments.some((value) => Boolean(value)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts index 5955252f5..4344f791f 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.memberWithGroups.ts @@ -39,7 +39,7 @@ export function memberWithGroups( ), ), ); - if (this.options.getValue('parametersFormat') === 'table') { + if (this.helpers.useTableFormat('parameters')) { md.push(this.partials.typeParametersTable(model.typeParameters)); } else { md.push(this.partials.typeParametersList(model.typeParameters)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts index 312d23c30..27d4eb3e6 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.parametersTable.ts @@ -10,8 +10,8 @@ export function parametersTable( this: MarkdownThemeContext, model: ParameterReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); - const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + const tableColumnsOptions = this.options.getValue('tableColumnSettings'); + const leftAlignHeadings = tableColumnsOptions.leftAlignHeaders; const parseParams = (current: any, acc: any) => { const shouldFlatten = diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts index 6664b77fe..8c7e82e60 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.propertiesTable.ts @@ -17,13 +17,13 @@ import { getPropertyDefaultValue } from '../helpers/get-property-default-value'; * @category Member Partials * */ -export function declarationsTable( +export function propertiesTable( this: MarkdownThemeContext, model: DeclarationReflection[], options?: { isEventProps: boolean }, ): string { - const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); - const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + const tableColumnsOptions = this.options.getValue('tableColumnSettings'); + const leftAlignHeadings = tableColumnsOptions.leftAlignHeaders; const modifiers = model.map((param) => this.helpers.getModifier(param)?.toString(), ); @@ -32,9 +32,6 @@ export function declarationsTable( !tableColumnsOptions.hideModifiers && modifiers.some((value) => Boolean(value)); - const flags = model.map((param) => this.partials.reflectionFlags(param)); - const hasFlags = flags.some((value) => Boolean(value)); - const hasOverrides = !tableColumnsOptions.hideOverrides && model.some((prop) => Boolean(prop.overwrites)); @@ -43,9 +40,9 @@ export function declarationsTable( !tableColumnsOptions.hideInherited && model.some((prop) => Boolean(prop.inheritedFrom)); - const hasDefaults = model.some((prop) => - Boolean(getPropertyDefaultValue(prop)), - ); + const hasDefaults = + !tableColumnsOptions.hideDefaults && + model.some((prop) => Boolean(getPropertyDefaultValue(prop))); const hasComments = model.some( (prop) => prop.comment?.blockTags?.length || prop?.comment?.summary?.length, ); @@ -66,10 +63,6 @@ export function declarationsTable( headers.push(this.i18n.theme_modifier()); } - if (hasFlags) { - headers.push(this.i18n.theme_flags()); - } - headers.push(this.i18n.theme_type()); if (hasDefaults) { @@ -118,16 +111,18 @@ export function declarationsTable( nameColumn.push(backTicks(propertyName)); } + const flags = this.helpers.getReflectionFlags(property); + + if (flags?.length) { + nameColumn.push(`(${flags.map((flag) => `*${flag}*`).join(', ')})`); + } + row.push(nameColumn.join(' ')); if (hasModifiers) { row.push(backTicks(modifiers[index] || 'public')); } - if (hasFlags) { - row.push(flags[index]); - } - if (propertyType) { const type = (propertyType as any).declaration?.signatures?.length ? this.partials.functionType( @@ -177,7 +172,10 @@ export function declarationsTable( rows.push(row); }); - return this.options.getValue('propertiesFormat') == 'table' - ? table(headers, rows, leftAlignHeadings) - : htmlTable(headers, rows, leftAlignHeadings); + const displayHtmlTable = + this.options.getValue('propertiesFormat') === 'htmlTable'; + + return displayHtmlTable + ? htmlTable(headers, rows, leftAlignHeadings) + : table(headers, rows, leftAlignHeadings); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts index 7f463b572..889b22cfb 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.signature.ts @@ -1,4 +1,4 @@ -import { heading } from '@plugin/libs/markdown'; +import { backTicks, heading } from '@plugin/libs/markdown'; import { MarkdownThemeContext } from '@plugin/theme'; import { ReflectionKind, SignatureReflection } from 'typedoc'; @@ -19,7 +19,12 @@ export function signature( ): string { const md: string[] = []; - md.push(this.partials.reflectionFlags(model)); + md.push( + this.helpers + .getReflectionFlags(model) + .map((item) => backTicks(item)) + .join(' '), + ); if (!options.nested) { md.push( @@ -60,7 +65,7 @@ export function signature( ), ), ); - if (this.options.getValue('parametersFormat') === 'table') { + if (this.helpers.useTableFormat('parameters')) { md.push(this.partials.typeParametersTable(model.typeParameters)); } else { md.push(this.partials.typeParametersList(model.typeParameters)); @@ -74,7 +79,7 @@ export function signature( this.internationalization.kindPluralString(ReflectionKind.Parameter), ), ); - if (this.options.getValue('parametersFormat') === 'table') { + if (this.helpers.useTableFormat('parameters')) { md.push(this.partials.parametersTable(model.parameters)); } else { md.push(this.partials.parametersList(model.parameters)); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.sources.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.sources.ts index 0fb3249ee..c45df9c00 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.sources.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.sources.ts @@ -14,7 +14,7 @@ export function sources( const md: string[] = []; if (options.headingLevel !== -1) { - md.push(heading(options.headingLevel, this.i18n.theme_source())); + md.push(heading(options.headingLevel, this.i18n.theme_defined_in())); } model.sources?.forEach((source, index) => { if (index === 0) { diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts index 83c45631e..c840484cc 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeDeclarationTable.ts @@ -10,8 +10,8 @@ export function typeDeclarationTable( this: MarkdownThemeContext, model: DeclarationReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); - const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + const tableColumnsOptions = this.options.getValue('tableColumnSettings'); + const leftAlignHeadings = tableColumnsOptions.leftAlignHeaders; const hasSources = !tableColumnsOptions.hideSources && @@ -27,9 +27,9 @@ export function typeDeclarationTable( Boolean(declaration.comment), ); - const hasDefaultValues = declarations.some((declaration) => - Boolean(declaration.defaultValue), - ); + const hasDefaultValues = + !tableColumnsOptions.hideValues && + declarations.some((declaration) => Boolean(declaration.defaultValue)); headers.push(this.i18n.theme_member()); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts index 0c2b2de7c..a6a88edc1 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.typeParametersTable.ts @@ -9,8 +9,7 @@ export function typeParametersTable( this: MarkdownThemeContext, model: TypeParameterReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); - const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + const tableColumnsOptions = this.options.getValue('tableColumnSettings'); const hasDefault = !tableColumnsOptions.hideDefaults && @@ -25,7 +24,7 @@ export function typeParametersTable( ]; if (hasDefault) { - headers.push(this.i18n.theme_value()); + headers.push(this.i18n.theme_default_type()); } if (hasComments) { @@ -70,6 +69,6 @@ export function typeParametersTable( }); return this.options.getValue('parametersFormat') == 'table' - ? table(headers, rows, leftAlignHeadings) - : htmlTable(headers, rows, leftAlignHeadings); + ? table(headers, rows, tableColumnsOptions.leftAlignHeaders) + : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeaders); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.breadcrumbs.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.breadcrumbs.ts index 8ab3cc779..38d926f3a 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.breadcrumbs.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.breadcrumbs.ts @@ -9,6 +9,7 @@ import * as path from 'path'; export function breadcrumbs(this: MarkdownThemeContext): string { const md: string[] = []; + const textContentMappings = this.options.getValue('textContentMappings'); const fileExtension = this.options.getValue('fileExtension'); const entryFileName = `${path.parse(this.options.getValue('entryFileName')).name}${fileExtension}`; @@ -20,13 +21,10 @@ export function breadcrumbs(this: MarkdownThemeContext): string { return ''; } - const name = this.page.project.name; - const version = this.page.project.packageVersion; - - const homeLabel = this.i18n - .theme_breadcrumbs_home(name, version ? `v${version}` : '') - .replace(/\s+/g, ' ') - .trim(); + const homeLabel = this.helpers.getProjectName( + textContentMappings['breadcrumbs.home'], + this.page, + ); md.push( link( diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.footer.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.footer.ts index 796b70c49..916aad05c 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.footer.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.footer.ts @@ -4,6 +4,7 @@ import { MarkdownThemeContext } from '@plugin/theme'; * @category Page Partials */ export function footer(this: MarkdownThemeContext): string { - const text = this.i18n.theme_footer_text(); + const textContentMappings = this.options.getValue('textContentMappings'); + const text = textContentMappings['footer.text']; return text ? `***\n\n${text}` : ``; } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.header.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.header.ts index a1e761d8f..a55e1d924 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.header.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.header.ts @@ -13,6 +13,8 @@ import { * @category Page Partials */ export function header(this: MarkdownThemeContext): string { + const textContentMappings = this.options.getValue('textContentMappings'); + const getHeader = () => { const isPackages = this.options.getValue('entryPointStrategy') === @@ -31,15 +33,13 @@ export function header(this: MarkdownThemeContext): string { const entryFileName = `${path.parse(this.options.getValue('entryFileName')).name}${fileExtension}`; const md: string[] = []; - const name = this.page.project.name; - const version = this.page.project.packageVersion; - const title = this.i18n - .theme_header_title(name, version ? `v${version}` : '') - .replace(/\s+/g, ' ') - .trim(); + const title = this.helpers.getProjectName( + textContentMappings['header.title'], + this.page, + ); - const indexLabel = this.i18n.theme_header_docs(); + const indexLabel = textContentMappings['header.docs']; if (this.page.url === entryFileName) { md.push(bold(title)); @@ -92,7 +92,7 @@ export function header(this: MarkdownThemeContext): string { const md: string[] = []; - const indexLabel = this.i18n.theme_header_docs(); + const indexLabel = textContentMappings['header.docs']; const ignoreScopes = this.options.getValue('excludeScopesInPaths'); const fileExtension = this.options.getValue('fileExtension'); diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts index de3576966..3c25bcd23 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.packagesIndex.ts @@ -11,7 +11,9 @@ export function packagesIndex( this: MarkdownThemeContext, model: ProjectReflection, ): string { - const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + const leftAlignHeadings = this.options.getValue( + 'tableColumnSettings', + ).leftAlignHeaders; const md: string[] = []; diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.pageTitle.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.pageTitle.ts index 50ab4c7c6..2b3f7d5e3 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.pageTitle.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.pageTitle.ts @@ -5,21 +5,21 @@ import { MarkdownThemeContext } from '../../..'; * @category Page Partials */ export function pageTitle(this: MarkdownThemeContext): string { + const textContentMappings = this.options.getValue('textContentMappings'); const page = this.page; if (page.model?.url === page.project.url) { - const titleContent = this.i18n.theme_title_index_page( - page.project.name, - page.project.packageVersion ? `v${page.project.packageVersion}` : '', + return this.helpers.getProjectName( + textContentMappings['title.indexPage'], + page, ); - return titleContent.replace(/\s+/g, ' ').trim(); } const name = this.partials.memberTitle(page.model as DeclarationReflection); - const moduleTitle = this.i18n.theme_title_module_page(name); - const memberTitle = this.i18n.theme_title_member_page( - this.internationalization.kindSingularString(page.model.kind), - name, - ); + const kind = this.internationalization.kindSingularString(page.model.kind); + const textContent = + page.model.kind === ReflectionKind.Module + ? name + : textContentMappings['title.memberPage']; - return page.model.kind === ReflectionKind.Module ? moduleTitle : memberTitle; + return textContent.replace('{name}', name).replace('{kind}', kind); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/templates/project.ts b/packages/typedoc-plugin-markdown/src/theme/resources/templates/project.ts index 51ee4efd0..5941ccb01 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/templates/project.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/templates/project.ts @@ -12,6 +12,8 @@ export function project( ) { const md: string[] = []; + const textContentMappings = this.options.getValue('textContentMappings'); + md.push(this.hook('index.page.begin').join('\n')); if (!this.options.getValue('hidePageHeader')) { @@ -41,7 +43,15 @@ export function project( if (page.model?.groups?.some((group) => group.allChildrenHaveOwnDocument())) { if (includeReadme) { - md.push(heading(2, this.i18n.theme_api_index())); + md.push( + heading( + 2, + this.helpers.getProjectName( + textContentMappings['title.indexPage'], + page, + ), + ), + ); } md.push( this.partials.documents(page.model, { diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts index 38b29afb2..83d386dfa 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/config.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/config.ts @@ -12,10 +12,11 @@ const config: Record = { ], hidePageHeader: true, hideBreadcrumbs: true, - tableColumnVisibility: { + tableColumnSettings: { hideSources: true, + leftAlignHeaders: true, }, - leftAlignTableHeaders: true, + excludePrivate: false, }, options: [ {}, @@ -43,7 +44,9 @@ const config: Record = { disableSources: true, expandObjects: true, expandParameters: true, - leftAlignTableHeaders: true, + tableColumnSettings: { + leftAlignHeaders: true, + }, }, options: [ {}, @@ -91,7 +94,9 @@ const config: Record = { theme: 'stub-groups', disableSources: true, entryFileName: 'index.md', - leftAlignTableHeaders: true, + tableColumnSettings: { + leftAlignHeaders: true, + }, }, options: [ { @@ -127,7 +132,7 @@ const config: Record = { hidePageHeader: true, hideBreadcrumbs: true, readme: 'none', - inlineDocuments: true, + excludePrivate: false, }, options: [ { @@ -146,14 +151,15 @@ const config: Record = { parametersFormat: 'htmlTable', propertiesFormat: 'htmlTable', typeDeclarationFormat: 'htmlTable', - tableColumnVisibility: { + tableColumnSettings: { hideDefaults: true, hideInherited: true, hideModifiers: true, hideOverrides: true, hideSources: true, + hideValues: true, + leftAlignHeaders: true, }, - leftAlignTableHeaders: true, }, ], }, @@ -165,7 +171,9 @@ const config: Record = { entryPointStrategy: 'packages', name: 'packages-example', disableSources: true, - leftAlignTableHeaders: true, + tableColumnSettings: { + leftAlignHeaders: true, + }, }, options: [ { entryFileName: 'index.md' }, @@ -219,6 +227,7 @@ const config: Record = { entryFileName: 'index.md', disableSources: true, mergeReadme: true, + includeVersion: true, }, ], }, @@ -228,13 +237,17 @@ const config: Record = { commonOptions: { plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')], disableSources: true, - leftAlignTableHeaders: true, + tableColumnSettings: { leftAlignHeaders: true }, + includeVersion: true, + propertiesFormat: 'table', + readme: 'none', }, options: [ { - includeVersion: true, - options: './test/fixtures/typedoc.text-options.cjs', - propertiesFormat: 'table', + options: './test/fixtures/typedoc.text-mappings.cjs', + }, + { + options: './test/fixtures/typedoc.text-locales.cjs', }, ], }, @@ -304,7 +317,6 @@ const config: Record = { {}, { indexFormat: 'table', - inlineDocuments: true, }, ], }, diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts index 5c721147c..1a732fd1e 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts @@ -151,6 +151,9 @@ export class BaseClassProperties { } export class ClassPropertiesTable extends BaseClassProperties { + /** @experimental */ + propWithFlag: string; + propA = 'propAValue'; /** * The subroutine recursively parsed the hexadecimal data. @@ -168,7 +171,7 @@ export class ClassPropertiesTable extends BaseClassProperties { /** * > Example of Triple Code Block * - * ```python + * ```ts * def greet(name): * print("Hello, " + name + "!") * ``` @@ -201,7 +204,7 @@ export interface InterfacePropertiesTable extends BaseInterfaceProperties { /** * > Example of Triple Code Block * - * ```python + * ```ts * def greet(name): * print("Hello, " + name + "!") * ``` @@ -221,6 +224,12 @@ export type TypeDeclarationTable = { */ declaration2: boolean; declaration3: 'declaration3'; + declaration4: 100; +}; + +export const TypeDeclarationTable = { + declaration1: 'declaration3', + declaration2: 100, }; /** diff --git a/packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-locales.cjs b/packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-locales.cjs new file mode 100644 index 000000000..2bbe5286d --- /dev/null +++ b/packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-locales.cjs @@ -0,0 +1,19 @@ +// @ts-check + +const baseOptions = require('../../../../devtools/packages/fixtures/typedoc.cjs'); + +/** @type {import('typedoc').TypeDocOptions} */ +module.exports = { + ...baseOptions, + textContentMappings: { + 'header.title': 'My API - {version} (ko)', + 'header.docs': 'Docs (ko)', + 'footer.text': 'Copyright Test (ko)', + }, + lang: 'ko', + locales: { + ko: { + theme_type: 'Type (ko)', + }, + }, +}; diff --git a/packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-options.cjs b/packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-mappings.cjs similarity index 59% rename from packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-options.cjs rename to packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-mappings.cjs index 220f27304..396eccbf6 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-options.cjs +++ b/packages/typedoc-plugin-markdown/test/fixtures/typedoc.text-mappings.cjs @@ -1,4 +1,8 @@ +// @ts-check + const baseOptions = require('../../../../devtools/packages/fixtures/typedoc.cjs'); + +/** @type {import('typedoc').TypeDocOptions} */ module.exports = { ...baseOptions, textContentMappings: { @@ -7,11 +11,12 @@ module.exports = { 'footer.text': 'Copyright Test', 'title.indexPage': ':tada: Custom Index Title', 'title.memberPage': '{name}', - 'title.modulePage': '{kind} - {name}', - 'label.source': 'Defined In', - 'kind.event.plural': 'My Events', - 'kind.event.singular': 'Event!', - 'kind.interface.plural': '多变的', - 'kind.variable.plural': 'CoolVars', + }, + locales: { + en: { + theme_index: 'TOC', + kind_plural_interface: 'CoolInterfaces', + kind_plural_variable: 'CoolVars', + }, }, }; diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap index 6f8b111f4..f141156de 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap @@ -70,9 +70,7 @@ And include other files: ## Documents -This is a simple example on how to use include. - -![My image alt text](media://logo.png) +- [example](documents/example.md) ## Enumerations @@ -99,6 +97,7 @@ This is a simple example on how to use include. ## Variables - [SameName](variables/SameName.md) +- [TypeDeclarationTable](variables/TypeDeclarationTable.md) - [\\_prop\\_with\\_underscore](variables/prop_with_underscore.md) - [prop](variables/prop.md) - [propb](variables/propb.md) @@ -116,7 +115,7 @@ exports[`Comments should get tables for emum: (Output File Strategy "members") ( ## Enumeration Members -| Enumeration Member | Value | Description | Defined in | +| Enumeration Member | Value | Description | Source | | ------ | ------ | ------ | ------ | | \`member1\` | \`"member1"\` | The subroutine recursively parsed the hexadecimal data. | [index.ts:1](http://source-url) | " @@ -159,13 +158,13 @@ Adds two numbers together. ## Type Parameters -| Type Parameter | Value | Description | +| Type Parameter | Default type | Description | | ------ | ------ | ------ | | \`T\` | \`string\` | The type of the numbers to be added. | ## Parameters -| Parameter | Type | Default Value | Description | +| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | \`param1\` | \`number\` | \`undefined\` | The first param to be added. | | \`param2\` | \`number\` | \`undefined\` | The second param to be added. Some additional text for num2. | @@ -204,13 +203,14 @@ exports[`Comments should get tables for properties: (Output File Strategy "membe ## Properties -| Property | Modifier | Type | Default Value | Description | Overrides | Inherited from | Defined in | +| Property | Modifier | Type | Default value | Description | Overrides | Inherited from | Source | | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | | \`prop1\` | \`private\` | \`boolean\` | \`undefined\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | - | - | [index.ts:1](http://source-url) | | \`prop2\` | \`readonly\` | \`RegExp\` | \`undefined\` | Below is a breakdown of the notable performances: - The CPU executed the instruction set in parallel with the GPU computations. - The RAM efficiently cached the frequently accessed data for faster retrieval. - The SSD accessed the stored files with lightning speed due to its high read/write capabilities. | - | - | [index.ts:1](http://source-url) | | \`prop3?\` | \`public\` | \`string\` | \`undefined\` | > Example of Triple Code Block \`def greet(name): print("Hello, " + name + "!")\` | - | - | [index.ts:1](http://source-url) | | ~~\`propA\`~~ | \`public\` | \`string\` | \`'propAValue'\` | **Deprecated** | [\`BaseClassProperties\`](BaseClassProperties.md).\`propA\` | - | [index.ts:1](http://source-url) | | \`propB\` | \`public\` | \`string\` | \`undefined\` | - | - | [\`BaseClassProperties\`](BaseClassProperties.md).\`propB\` | [index.ts:1](http://source-url) | +| \`propWithFlag\` (*Experimental*) | \`public\` | \`string\` | \`undefined\` | - | - | - | [index.ts:1](http://source-url) | " `; @@ -240,7 +240,7 @@ exports[`Comments should get tables for properties: (Output File Strategy "membe ## Properties - + - - - - @@ -352,7 +332,19 @@ print("Hello, " + name + "!") + + + + + + + + + + +
PropertyTypeDefault ValueDescription
PropertyTypeDescription
@@ -254,11 +254,6 @@ exports[`Comments should get tables for properties: (Output File Strategy "membe -\`undefined\` - - - The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. @@ -277,11 +272,6 @@ to generate the binary output for input validation. -\`undefined\` - - - Below is a breakdown of the notable performances: - The CPU executed the instruction set in parallel with the GPU computations. @@ -303,14 +293,9 @@ Below is a breakdown of the notable performances: -\`undefined\` - - - > Example of Triple Code Block -\`\`\`python +\`\`\`ts def greet(name): print("Hello, " + name + "!") \`\`\` @@ -330,11 +315,6 @@ print("Hello, " + name + "!") -\`'propAValue'\` - - - **Deprecated** -\`undefined\` +‐ + +
+ + \`propWithFlag\` (*Experimental*) + + + +\`string\` @@ -372,11 +364,30 @@ exports[`Comments should get tables for type declarations: (Output File Strategy ## Type declaration -| Member | Type | Description | Defined in | +| Member | Type | Description | Source | | ------ | ------ | ------ | ------ | | \`declaration1\` | \`boolean\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | [index.ts:1](http://source-url) | | \`declaration2\` | \`boolean\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | [index.ts:1](http://source-url) | | \`declaration3\` | \`"declaration3"\` | - | [index.ts:1](http://source-url) | +| \`declaration4\` | \`100\` | - | [index.ts:1](http://source-url) | + +## Source + +[index.ts:1](http://source-url) +" +`; + +exports[`Comments should get tables for type declarations: (Output File Strategy "members") (Option Group "1") 2`] = ` +"# Variable: TypeDeclarationTable + +> **TypeDeclarationTable**: \`object\` + +## Type declaration + +| Member | Type | Value | Source | +| ------ | ------ | ------ | ------ | +| \`declaration1\` | \`string\` | 'declaration3' | [index.ts:1](http://source-url) | +| \`declaration2\` | \`number\` | 100 | [index.ts:1](http://source-url) | ## Source @@ -444,6 +455,64 @@ to generate the binary output for input validation. ‐ +
+ +\`declaration4\` + + + +\`100\` + + + +‐ + +
+ +## Source + +[index.ts:1](http://source-url) +" +`; + +exports[`Comments should get tables for type declarations: (Output File Strategy "members") (Option Group "2") 2`] = ` +"# Variable: TypeDeclarationTable + +> **TypeDeclarationTable**: \`object\` + +## Type declaration + + + + + + + + + +
MemberType
+ +\`declaration1\` + + + +\`string\` + +
+ +\`declaration2\` + + + +\`number\` +
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap index f05e9aa4a..f98dd9793 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap @@ -623,7 +623,7 @@ exports[`Navigation should get Navigation Json for packages: (Output File Strate "kind": 2, "children": [ { - "title": "Globals", + "title": "Modules", "path": "@scope/package-1/globals.md", "kind": 2 } @@ -1868,15 +1868,18 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou "children": [ { "title": "Project Document 1", - "kind": 8388608 + "kind": 8388608, + "path": "documents/Project-Document-1.md" }, { "title": "docs/project/PROJECT_DOC_2", - "kind": 8388608 + "kind": 8388608, + "path": "documents/docs/project/PROJECT_DOC_2.md" }, { "title": "docs/project/PROJECT_DOC_3", - "kind": 8388608 + "kind": 8388608, + "path": "documents/docs/project/PROJECT_DOC_3.md" } ] }, @@ -1885,6 +1888,11 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou "kind": 2, "path": "ModuleWithDocuments1/README.md", "children": [ + { + "title": "MODULE_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/documents/MODULE_DOC.md" + }, { "title": "Namespaces", "children": [ @@ -1893,13 +1901,25 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou "kind": 4, "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/README.md", "children": [ + { + "title": "NAMESPACE_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/documents/NAMESPACE_DOC.md" + }, { "title": "Classes", "children": [ { "title": "NamespaceClassWithDocuments", "kind": 128, - "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/classes/NamespaceClassWithDocuments.md" + "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/classes/NamespaceClassWithDocuments.md", + "children": [ + { + "title": "CLASS_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/classes/documents/CLASS_DOC.md" + } + ] } ] } @@ -1913,7 +1933,14 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou { "title": "EnumWithDocuments", "kind": 8, - "path": "ModuleWithDocuments1/enumerations/EnumWithDocuments.md" + "path": "ModuleWithDocuments1/enumerations/EnumWithDocuments.md", + "children": [ + { + "title": "ENUM_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/enumerations/documents/ENUM_DOC.md" + } + ] } ] }, @@ -1923,7 +1950,14 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou { "title": "ClassWithDocuments", "kind": 128, - "path": "ModuleWithDocuments1/classes/ClassWithDocuments.md" + "path": "ModuleWithDocuments1/classes/ClassWithDocuments.md", + "children": [ + { + "title": "CLASS_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/classes/documents/CLASS_DOC.md" + } + ] } ] }, @@ -1933,7 +1967,14 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou { "title": "InterfaceWithDocuments", "kind": 256, - "path": "ModuleWithDocuments1/interfaces/InterfaceWithDocuments.md" + "path": "ModuleWithDocuments1/interfaces/InterfaceWithDocuments.md", + "children": [ + { + "title": "INTERFACE_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/interfaces/documents/INTERFACE_DOC.md" + } + ] } ] }, @@ -1943,7 +1984,14 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou { "title": "TypeWithDocuments", "kind": 2097152, - "path": "ModuleWithDocuments1/type-aliases/TypeWithDocuments.md" + "path": "ModuleWithDocuments1/type-aliases/TypeWithDocuments.md", + "children": [ + { + "title": "TYPE_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/type-aliases/documents/TYPE_DOC.md" + } + ] } ] }, @@ -1953,7 +2001,14 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou { "title": "variableWithDocuments", "kind": 32, - "path": "ModuleWithDocuments1/variables/variableWithDocuments.md" + "path": "ModuleWithDocuments1/variables/variableWithDocuments.md", + "children": [ + { + "title": "VARIABLE_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/variables/documents/VARIABLE_DOC.md" + } + ] } ] }, @@ -1963,12 +2018,26 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou { "title": "functionWithDocuments", "kind": 64, - "path": "ModuleWithDocuments1/functions/functionWithDocuments.md" + "path": "ModuleWithDocuments1/functions/functionWithDocuments.md", + "children": [ + { + "title": "FUNCTION_DOC_1", + "kind": 8388608, + "path": "ModuleWithDocuments1/functions/documents/FUNCTION_DOC_1.md" + } + ] }, { "title": "multipleFunctionWithDocuments", "kind": 64, - "path": "ModuleWithDocuments1/functions/multipleFunctionWithDocuments.md" + "path": "ModuleWithDocuments1/functions/multipleFunctionWithDocuments.md", + "children": [ + { + "title": "FUNCTION_DOC_1", + "kind": 8388608, + "path": "ModuleWithDocuments1/functions/documents/FUNCTION_DOC_1.md" + } + ] } ] } @@ -2038,15 +2107,18 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou "children": [ { "title": "Project Document 1", - "kind": 8388608 + "kind": 8388608, + "path": "documents/Project-Document-1.md" }, { "title": "docs/project/PROJECT_DOC_2", - "kind": 8388608 + "kind": 8388608, + "path": "documents/docs/project/PROJECT_DOC_2.md" }, { "title": "docs/project/PROJECT_DOC_3", - "kind": 8388608 + "kind": 8388608, + "path": "documents/docs/project/PROJECT_DOC_3.md" } ] }, @@ -2055,13 +2127,25 @@ exports[`Navigation should gets Navigation Json for documents single module: (Ou "kind": 2, "path": "ModuleWithDocuments1/README.md", "children": [ + { + "title": "MODULE_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/documents/MODULE_DOC.md" + }, { "title": "Namespaces", "children": [ { "title": "NamespaceWithDocuments", "kind": 4, - "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/README.md" + "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/README.md", + "children": [ + { + "title": "NAMESPACE_DOC", + "kind": 8388608, + "path": "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/documents/NAMESPACE_DOC.md" + } + ] } ] } diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap index 05150ad2a..a6ed4e42f 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap @@ -5,7 +5,7 @@ exports[`Objects And Params should compile basic interface: (Output File Strateg Comments for BasicInterface -## Extended By +## Extended by - [\`ExtendedInterface\`](ExtendedInterface.md) @@ -196,7 +196,7 @@ exports[`Objects And Params should compile basic interface: (Output File Strateg Comments for BasicInterface -## Extended By +## Extended by - [\`ExtendedInterface\`](ExtendedInterface.md) diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/readme.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/readme.spec.ts.snap index ea83182e4..6d03db8d1 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/readme.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/readme.spec.ts.snap @@ -1,7 +1,7 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP exports[`Readmes should get merged readme for members: (Output File Strategy "members") (Option Group "1") 1`] = ` -"**typedoc-stubs** • **Docs** +"**typedoc-stubs v0.0** • **Docs** *** @@ -17,7 +17,7 @@ Some text. Module commments -## API Index +## typedoc-stubs v0.0 ### Functions @@ -26,7 +26,7 @@ Module commments `; exports[`Readmes should get merged readme for modules: (Output File Strategy "modules") (Option Group "1") 1`] = ` -"**typedoc-stubs** • **Docs** +"**typedoc-stubs v0.0** • **Docs** *** diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.class.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.class.spec.ts.snap index 1f71999e8..71f500c79 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.class.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.class.spec.ts.snap @@ -3,7 +3,7 @@ exports[`Class Reflection should compile abstract class: (Output File Strategy "members") (Option Group "1") 1`] = ` "# Class: \`abstract\` AbstractClass -## Extended By +## Extended by - [\`DerivedClassA\`](DerivedClassA.md) - [\`DerivedClassB\`](DerivedClassB.md) @@ -51,7 +51,7 @@ Comments for abstractMethod exports[`Class Reflection should compile abstract class: (Output File Strategy "members") (Option Group "2") 1`] = ` "# Class: \`abstract\` AbstractClass -## Extended By +## Extended by - [\`DerivedClassA\`](DerivedClassA.md) - [\`DerivedClassB\`](DerivedClassB.md) @@ -418,7 +418,7 @@ new ClassWithComplexProps(): ClassWithComplexProps ## Properties -| Property | Type | Default Value | +| Property | Type | Default value | | :------ | :------ | :------ | | \`objecLiteralProp\` | \`object\` | \`...\` | | \`objecLiteralProp.someFunction\` | (\`a\`: \`string\`) => \`string\` | \`...\` | @@ -651,10 +651,10 @@ new ClassWithFlags(): ClassWithFlags ## Properties -| Property | Modifier | Flags | Type | -| :------ | :------ | :------ | :------ | -| \`expermintalProp\` | \`public\` | \`Experimental\` | \`string\` | -| \`internalProp\` | \`private\` | \`Internal\` | \`string\` | +| Property | Modifier | Type | +| :------ | :------ | :------ | +| \`expermintalProp\` (*Experimental*) | \`public\` | \`string\` | +| \`internalProp\` (*Internal*) | \`private\` | \`string\` | ## Methods @@ -838,7 +838,7 @@ new ClassWithModifiers(): ClassWithModifiers ## Properties -| Property | Modifier | Type | Default Value | Description | +| Property | Modifier | Type | Default value | Description | | :------ | :------ | :------ | :------ | :------ | | \`privateProp\` | \`private\` | \`string\` | \`undefined\` | Comments for privateProp | | \`protectedProp\` | \`protected\` | \`string\` | \`undefined\` | Comments for protectedProp | @@ -999,7 +999,7 @@ new ClassWithSimpleProps(): ClassWithSimpleProps ## Properties -| Property | Type | Default Value | Description | +| Property | Type | Default value | Description | | :------ | :------ | :------ | :------ | | \`propA\` | \`string\` | \`'propAValue'\` | Comments for propA | | \`propB\` | \`string\` | \`'propBDefaultValue'\` | Comments for propB | @@ -1087,7 +1087,7 @@ Comments for ClassWithTypeParameters ## Type Parameters -| Type Parameter | Value | Description | +| Type Parameter | Default type | Description | | :------ | :------ | :------ | | \`A\` | - | Comments for param A | | \`B\` *extends* \`string\` | - | Comments for param B | @@ -1219,7 +1219,7 @@ new DerivedClassA(): DerivedClassA ## Properties -| Property | Type | Default Value | Description | Overrides | +| Property | Type | Default value | Description | Overrides | | :------ | :------ | :------ | :------ | :------ | | \`abstractProp\` | \`string\` | \`'abstractProp'\` | Comments for abstractProp | [\`AbstractClass\`](AbstractClass.md).\`abstractProp\` | | \`derivedProp\` | \`string\` | \`undefined\` | - | - | @@ -1304,7 +1304,7 @@ exports[`Class Reflection should compile disposable class: (Output File Strategy exports[`Class Reflection should compile hierarchy for BaseClass: (Output File Strategy "members") (Option Group "1") 1`] = ` "# Class: BaseClass -## Extended By +## Extended by - [\`ChildClassA\`](ChildClassA.md) - [\`ChildClassB\`](ChildClassB.md) @@ -1328,7 +1328,7 @@ exports[`Class Reflection should compile hierarchy for ChildClassA: (Output File - [\`BaseClass\`](BaseClass.md) -## Extended By +## Extended by - [\`GrandChildClassA\`](GrandChildClassA.md) - [\`GrandChildClassB\`](GrandChildClassB.md) diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap index 0fe1fe726..ef8985422 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap @@ -415,7 +415,7 @@ This is a function with a parameter that has a default value. ## Parameters -| Parameter | Type | Default Value | Description | +| Parameter | Type | Default value | Description | | :------ | :------ | :------ | :------ | | \`valueA\` | \`string\` | \`'defaultValue'\` | A parameter with a default string value. | | \`valueB\` | \`number\` | \`100\` | A parameter with a default numeric value. | @@ -753,7 +753,7 @@ This is a function with a parameters. ## Parameters -| Parameter | Type | Default Value | Description | +| Parameter | Type | Default value | Description | | :------ | :------ | :------ | :------ | | \`firstParamWithDefault\` | \`boolean\` | \`true\` | - | | \`requiredParam\` | \`string\` | \`undefined\` | A normal parameter. | @@ -785,7 +785,7 @@ This is a function with a parameters. ## Parameters -| Parameter | Type | Default Value | Description | +| Parameter | Type | Default value | Description | | :------ | :------ | :------ | :------ | | \`firstParamWithDefault\` | \`boolean\` | \`true\` | - | | \`requiredParam\` | \`string\` | \`undefined\` | A normal parameter. | @@ -887,7 +887,7 @@ Function with type parameters ## Type Parameters -| Type Parameter | Value | Description | +| Type Parameter | Default type | Description | | :------ | :------ | :------ | | \`T\` | - | Comments for T | | \`Item\` | \`string\` \\| \`boolean\` | - | diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap index 0378b01da..0d01ac75d 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap @@ -5,7 +5,7 @@ exports[`Interface Reflection should compile basic interface: (Output File Strat Comments for BasicInterface -## Extended By +## Extended by - [\`ExtendedInterface\`](ExtendedInterface.md) @@ -236,7 +236,7 @@ exports[`Interface Reflection should compile basic interface: (Output File Strat Comments for BasicInterface -## Extended By +## Extended by - [\`ExtendedInterface\`](ExtendedInterface.md) @@ -812,10 +812,10 @@ Comments for InterfaceWithFlags ## Properties -| Property | Flags | Type | -| :------ | :------ | :------ | -| \`expermintalProp?\` | \`Experimental\` | \`string\` | -| \`internalProp\` | \`Internal\` | \`string\` | +| Property | Type | +| :------ | :------ | +| \`expermintalProp?\` (*Experimental*) | \`string\` | +| \`internalProp\` (*Internal*) | \`string\` | " `; diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/text.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/text.spec.ts.snap index fae1e209b..4adf03b1d 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/text.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/text.spec.ts.snap @@ -1,7 +1,7 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP exports[`Text should get translations for index page: (Output File Strategy "members") (Option Group "1") 1`] = ` -"[**My API - v0.0**](README.md) • **API** +"**My API - v0.0** • **API** *** @@ -18,12 +18,30 @@ Copyright Test " `; +exports[`Text should get translations for index page: (Output File Strategy "members") (Option Group "2") 1`] = ` +"**My API - v0.0 (ko)** • **Docs (ko)** + +*** + +# typedoc-stubs v0.0 + +## 모듈 + +- [module-1](module-1/README.md) +- [module-2](module-2/README.md) + +*** + +Copyright Test (ko) +" +`; + exports[`Text should get translations for member page: (Output File Strategy "members") (Option Group "1") 1`] = ` "[**My API - v0.0**](../../README.md) • **API** *** -[typedoc-stubs v0.0](../../modules.md) / [module-1](../README.md) / SomeInterface +[typedoc-stubs v0.0](../../README.md) / [module-1](../README.md) / SomeInterface # SomeInterface @@ -45,18 +63,45 @@ Copyright Test " `; +exports[`Text should get translations for member page: (Output File Strategy "members") (Option Group "2") 1`] = ` +"[**My API - v0.0 (ko)**](../../README.md) • **Docs (ko)** + +*** + +[typedoc-stubs v0.0](../../README.md) / [module-1](../README.md) / SomeInterface + +# 인터페이스: SomeInterface + +## 속성 + +| 속성 | Type (ko) | 설명 | +| :------ | :------ | :------ | +| \`someProp?\` | \`boolean\` | Description for prop someProp | + +## Events + +| 이벤트 | Type (ko) | +| :------ | :------ | +| \`someEvent\` | \`MouseEvent\` | + +*** + +Copyright Test (ko) +" +`; + exports[`Text should get translations for module page: (Output File Strategy "members") (Option Group "1") 1`] = ` "[**My API - v0.0**](../README.md) • **API** *** -[typedoc-stubs v0.0](../modules.md) / module-1 +[typedoc-stubs v0.0](../README.md) / module-1 -# module-1 - module-1 +# module-1 -## Index +## TOC -### Interfaces +### CoolInterfaces - [SomeInterface](interfaces/SomeInterface.md) @@ -71,11 +116,11 @@ exports[`Text should get translations for modules page: (Output File Strategy "m *** -[typedoc-stubs v0.0](modules.md) / module-2 +[typedoc-stubs v0.0](README.md) / module-2 -# module-2 - module-2 +# module-2 -## Variables +## CoolVars ### constA @@ -95,7 +140,7 @@ exports[`Text should get translations for sidebar: (Output File Strategy "member "path": "module-1/README.md", "children": [ { - "title": "Interfaces", + "title": "CoolInterfaces", "children": [ { "title": "SomeInterface", @@ -112,7 +157,7 @@ exports[`Text should get translations for sidebar: (Output File Strategy "member "path": "module-2/README.md", "children": [ { - "title": "Variables", + "title": "CoolVars", "children": [ { "title": "constA", 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 index 69577abee..e64143b30 100644 --- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap +++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap @@ -185,15 +185,29 @@ exports[`Urls should gets Urls for documents single module: outputFileStrategy: [ "ModuleWithDocuments1/README.md", "ModuleWithDocuments1/classes/ClassWithDocuments.md", + "ModuleWithDocuments1/classes/documents/CLASS_DOC.md", + "ModuleWithDocuments1/documents/MODULE_DOC.md", "ModuleWithDocuments1/enumerations/EnumWithDocuments.md", + "ModuleWithDocuments1/enumerations/documents/ENUM_DOC.md", + "ModuleWithDocuments1/functions/documents/FUNCTION_DOC_1.md", + "ModuleWithDocuments1/functions/documents/FUNCTION_DOC_2.md", + "ModuleWithDocuments1/functions/documents/FUNCTION_DOC_3.md", "ModuleWithDocuments1/functions/functionWithDocuments.md", "ModuleWithDocuments1/functions/multipleFunctionWithDocuments.md", "ModuleWithDocuments1/interfaces/InterfaceWithDocuments.md", + "ModuleWithDocuments1/interfaces/documents/INTERFACE_DOC.md", "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/README.md", "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/classes/NamespaceClassWithDocuments.md", + "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/classes/documents/CLASS_DOC.md", + "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/documents/NAMESPACE_DOC.md", "ModuleWithDocuments1/type-aliases/TypeWithDocuments.md", + "ModuleWithDocuments1/type-aliases/documents/TYPE_DOC.md", + "ModuleWithDocuments1/variables/documents/VARIABLE_DOC.md", "ModuleWithDocuments1/variables/variableWithDocuments.md", "README.md", + "documents/Project-Document-1.md", + "documents/docs/project/PROJECT_DOC_2.md", + "documents/docs/project/PROJECT_DOC_3.md", ] `; @@ -222,8 +236,22 @@ exports[`Urls should gets Urls for documents single module: outputFileStrategy: exports[`Urls should gets Urls for documents single module: outputFileStrategy: modules 2`] = ` [ "ModuleWithDocuments1/README.md", + "ModuleWithDocuments1/documents/Class.CLASS_DOC.md", + "ModuleWithDocuments1/documents/Enumeration.ENUM_DOC.md", + "ModuleWithDocuments1/documents/Function.FUNCTION_DOC_1.md", + "ModuleWithDocuments1/documents/Function.FUNCTION_DOC_2.md", + "ModuleWithDocuments1/documents/Function.FUNCTION_DOC_3.md", + "ModuleWithDocuments1/documents/Interface.INTERFACE_DOC.md", + "ModuleWithDocuments1/documents/MODULE_DOC.md", + "ModuleWithDocuments1/documents/TypeAlias.TYPE_DOC.md", + "ModuleWithDocuments1/documents/Variable.VARIABLE_DOC.md", "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/README.md", + "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/documents/Class.CLASS_DOC.md", + "ModuleWithDocuments1/namespaces/NamespaceWithDocuments/documents/NAMESPACE_DOC.md", "README.md", + "documents/Project-Document-1.md", + "documents/docs/project/PROJECT_DOC_2.md", + "documents/docs/project/PROJECT_DOC_3.md", ] `; diff --git a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts index 19254e980..ef29d6101 100644 --- a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts +++ b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts @@ -37,6 +37,10 @@ describe(`Comments`, () => { '/type-aliases/TypeDeclarationTable.md', '/TypeAlias.TypeDeclarationTable.md', ]); + expectFileToEqual('comments', 'members', [ + '/variables/TypeDeclarationTable.md', + '/Variable.TypeDeclarationTable.md', + ]); }); test(`should get tables for emum`, () => { diff --git a/packages/typedoc-plugin-markdown/test/specs/text.spec.ts b/packages/typedoc-plugin-markdown/test/specs/text.spec.ts index ee7a8dad0..d3849ec64 100644 --- a/packages/typedoc-plugin-markdown/test/specs/text.spec.ts +++ b/packages/typedoc-plugin-markdown/test/specs/text.spec.ts @@ -2,7 +2,7 @@ import { expectFileToEqual } from '@devtools/testing'; describe(`Text`, () => { test(`should get translations for index page`, () => { - expectFileToEqual('text', 'members', ['modules.md']); + expectFileToEqual('text', 'members', 'README.md'); }); test(`should get translations for module page`, () => { @@ -10,9 +10,11 @@ describe(`Text`, () => { }); test(`should get translations for member page`, () => { - expectFileToEqual('text', 'members', [ + expectFileToEqual( + 'text', + 'members', 'module-1/interfaces/SomeInterface.md', - ]); + ); }); test(`should get translations for modules page`, () => {