diff --git a/devtools/packages/helpers/constants.ts b/devtools/packages/helpers/constants.ts index 253b0ea78..8e42ba188 100644 --- a/devtools/packages/helpers/constants.ts +++ b/devtools/packages/helpers/constants.ts @@ -11,6 +11,13 @@ export const DOCS_CONFIG: Record = { docsPath: '/docs', declarations: true, presets: false, + categories: { + file: 'Options that are used to configure how files are output.', + display: + 'Options that are used to configure how the output is structured and displayed .', + utility: + 'Options that are used for general configuration and utility purposes.', + }, }, ['typedoc-plugin-frontmatter']: { declarationsPath: `${process.cwd()}/src/options/declarations.ts`, diff --git a/devtools/packages/helpers/models.ts b/devtools/packages/helpers/models.ts index 5657b833b..e745fa216 100644 --- a/devtools/packages/helpers/models.ts +++ b/devtools/packages/helpers/models.ts @@ -6,6 +6,7 @@ export interface DocsConfig { docsPath: string; declarations: boolean; presets: boolean; + categories?: Record; } export interface OptionDocument { diff --git a/devtools/packages/prebuild-options/tasks/generate-docs.ts b/devtools/packages/prebuild-options/tasks/generate-docs.ts index 5146983f0..e576165c3 100644 --- a/devtools/packages/prebuild-options/tasks/generate-docs.ts +++ b/devtools/packages/prebuild-options/tasks/generate-docs.ts @@ -10,40 +10,40 @@ export async function generateOptionsDocs(docsConfig: DocsConfig) { tsConfigFilePath: 'tsconfig.json', }); - // PRESETS - const out: string[] = [ + const outputPage: string[] = [ `import { Callout, FileTree } from 'nextra/components';`, ]; - out.push('# Options'); + outputPage.push('# Options'); if (docsConfig.docsPath === '/docs') { - out.push( - `These options should be used in conjunction with core TypeDoc options (see [TypeDoc Usage](/docs/typedoc-usage)).`, + outputPage.push( + `These options should be used in conjunction with the core TypeDoc options (see [TypeDoc Usage](/docs/typedoc-usage)).`, ); } else { if (docsConfig.presets) { - out.push( + outputPage.push( `Please view options exposed by [typedoc-plugin-markdown](/docs/options) in addition to those listed here.`, ); } } if (docsConfig.presets) { - out.push('## Preset Options'); - out.push('The following are preset typedoc-plugin-markdown options:'); + outputPage.push('## Preset Options'); + outputPage.push( + 'The following are preset typedoc-plugin-markdown options:', + ); const presetsConfig: any = await import(docsConfig.presetsPath as string); const config = presetsConfig.default; delete config.plugin; const presetsJson = JSON.stringify(config, null, 2); - out.push(`\`\`\`json" + outputPage.push(`\`\`\`json" ${presetsJson} \`\`\``); - out.push('## Plugin Options'); - out.push('The following options are exposed by this plugin:'); + outputPage.push('## Plugin Options'); + outputPage.push('The following options are exposed by this plugin:'); } - // DECLARATIONS if (docsConfig.declarations) { const declarationsConfig: any = await import( docsConfig.declarationsPath as string @@ -55,8 +55,8 @@ ${presetsJson} const optionsVariableStatements = configFileTs?.getVariableStatements() as VariableStatement[]; - const parsedConfig = Object.entries(declarationsConfig).map( - ([name, option]: any, i) => { + const parsedConfig = Object.entries(declarationsConfig) + .map(([name, option]: any, i) => { const docs = optionsVariableStatements[i].getJsDocs().map((doc) => { return { comments: (doc.getComment() as string) @@ -75,6 +75,9 @@ ${presetsJson} name: tag.getTagName(), comments: tag.getComment(), })), + hidden: Boolean( + doc.getTags().find((tag) => tag.getTagName() === 'hidden'), + ), omitExample: Boolean( doc.getTags().find((tag) => tag.getTagName() === 'omitExample'), ), @@ -98,8 +101,8 @@ ${presetsJson} ...option, ...(docs ? docs : { category: 'other' }), }; - }, - ); + }) + .filter((option) => !option.hidden); const groupedConfig: Record = groupBy( parsedConfig, @@ -108,27 +111,47 @@ ${presetsJson} const categories = Object.entries(groupedConfig); - categories.forEach(([categoryName, options]) => { + categories.forEach(async ([categoryName, options]) => { + const out: string[] = [ + categories.length > 1 + ? `import { Callout, FileTree } from 'nextra/components';` + : '', + ]; const optionLevel = - categories.length === 1 && !Boolean(docsConfig.presets) ? '##' : '###'; + categories.length === 1 && !Boolean(docsConfig.presets) ? '##' : '##'; if (categories.length > 1) { - out.push(`## ${getDocsTitle(categoryName)}`); + out.push(`# ${getDocsTitle(categoryName)}`); + outputPage.push(`## ${getDocsTitle(categoryName)}`); + if (docsConfig.categories) { + outputPage.push(docsConfig.categories[categoryName.toLowerCase()]); + } } + const optionsLi: string[] = []; options.forEach((option) => { + optionsLi.push( + `- [${ + Boolean(option.deprecated) + ? `~--${option.name}~` + : `--${option.name}` + }](./options/${categoryName.toLowerCase()}-options.mdx#--${option.name.toLowerCase()})`, + ); out.push( `${optionLevel} ${ - Boolean(option.deprecated) ? `~${option.name}~` : `${option.name}` + Boolean(option.deprecated) + ? `~--${option.name}~` + : `--${option.name}` }`, ); if (Boolean(option.deprecated)) { out.push( - `Deprecated - ${option.deprecated}`, + `Deprecated: ${option.deprecated}`, ); } else { out.push( `${option.help}`, ); } + const meta: string[] = []; const type = getType(option); if (type) { @@ -160,34 +183,68 @@ ${presetsJson} ) { //out.push('Below is the full list of keys and default values:'); } - - out.push(` + } + out.push(` \`\`\`json filename="typedoc.json" ${JSON.stringify( JSON.parse(`{ - "${option.name}": ${getExampleValue(option)} -}`), + "${option.name}": ${getExampleValue(option)} + }`), null, 2, )} - \`\`\``); - } - out.push('___'); }); + if (categories.length > 1) { + outputPage.push(optionsLi.join('\n')); + const catDocPath = path.join( + getPagesPath(docsConfig.optionsPath), + 'options', + `${categoryName.toLowerCase()}-options.mdx`, + ); + const formattedOut = await prettier.format(out.join('\n\n'), { + parser: 'mdx', + }); + fs.writeFileSync(catDocPath, formattedOut); + } else { + outputPage.push(out.join('\n\n')); + } }); - } + if (categories.length > 1) { + const metaJs = await prettier.format( + `export default ${JSON.stringify( + categories.reduce((prev, curr) => { + return { + ...prev, + [`${curr[0].toLowerCase()}-options`]: '', + }; + }, {}), + )}`, + { + parser: 'typescript', + }, + ); - const optionDocPath = path.join( - getPagesPath(docsConfig.optionsPath), - 'options.mdx', - ); + const metaJsPath = path.join( + getPagesPath(docsConfig.optionsPath), + 'options', + '_meta.js', + ); - const formattedOut = await prettier.format(out.join('\n\n'), { - parser: 'mdx', - }); + fs.writeFileSync(metaJsPath, metaJs); + } + + const optionDocPath = path.join( + getPagesPath(docsConfig.optionsPath), + 'options.mdx', + ); - fs.writeFileSync(optionDocPath, formattedOut); + const formattedOut = await prettier.format(outputPage.join('\n\n'), { + parser: 'mdx', + }); + + fs.writeFileSync(optionDocPath, formattedOut); + } } function getEmoji(categoryName: string) { diff --git a/devtools/packages/prebuild-options/tasks/generate-models.ts b/devtools/packages/prebuild-options/tasks/generate-models.ts index 7d006ec85..998263387 100644 --- a/devtools/packages/prebuild-options/tasks/generate-models.ts +++ b/devtools/packages/prebuild-options/tasks/generate-models.ts @@ -193,12 +193,12 @@ function getType( .join(';')}}`; } if (option.type === ParameterType.Mixed && option.defaultValue) { - const usePartial = name === 'textContentMappings'; + const useAny = name === 'textContentMappings'; return isInterface - ? usePartial - ? `Partial<${capitalize(name)}>` + ? useAny + ? `Partial` : capitalize(name) - : usePartial + : useAny ? `ManuallyValidatedOption>` : `ManuallyValidatedOption<${capitalize(name)}>`; } diff --git a/docs/global.css b/docs/global.css index 9784c1a49..3e9a4abc0 100644 --- a/docs/global.css +++ b/docs/global.css @@ -6,7 +6,8 @@ .nextra-toc a[href^='#parameters-'], .nextra-toc a[href^='#returns'], .nextra-toc a[href^='#source'], -.nextra-toc a[href^='#overrides'] { +.nextra-toc a[href^='#overrides'], +.nextra-toc a[href^='#deprecated'] { display: none; } blockquote { diff --git a/docs/pages/api-docs/Class.MarkdownPageEvent.md b/docs/pages/api-docs/Class.MarkdownPageEvent.md index 069f92418..553fa0bcf 100644 --- a/docs/pages/api-docs/Class.MarkdownPageEvent.md +++ b/docs/pages/api-docs/Class.MarkdownPageEvent.md @@ -14,13 +14,13 @@ export function load(app: MarkdownApplication) { ## Extends -- [`Event ↗️`]( https://typedoc.org/api/classes/Event.html ) +- [`Event`](https://typedoc.org/api/classes/Event.html) ## Properties ### project -> **project**: [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) +> **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) The project the renderer is currently processing. diff --git a/docs/pages/api-docs/Class.MarkdownRendererEvent.md b/docs/pages/api-docs/Class.MarkdownRendererEvent.md index d21885441..be21c5003 100644 --- a/docs/pages/api-docs/Class.MarkdownRendererEvent.md +++ b/docs/pages/api-docs/Class.MarkdownRendererEvent.md @@ -12,13 +12,13 @@ app.renderer.on(MarkdownRendererEvent.BEGIN, (event) => { ## Extends -- [`Event ↗️`]( https://typedoc.org/api/classes/Event.html ) +- [`Event`](https://typedoc.org/api/classes/Event.html) ## Properties ### project -> `readonly` **project**: [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) +> `readonly` **project**: [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) The project the renderer is currently processing. @@ -34,7 +34,7 @@ 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 )\>[] +> `optional` **urls**: [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[] A list of all pages that should be generated. diff --git a/docs/pages/api-docs/Class.MarkdownTheme.md b/docs/pages/api-docs/Class.MarkdownTheme.md index c1d963129..8855ff51b 100644 --- a/docs/pages/api-docs/Class.MarkdownTheme.md +++ b/docs/pages/api-docs/Class.MarkdownTheme.md @@ -22,7 +22,7 @@ class MyMarkdownTheme extends MarkdownTheme { ## Extends -- [`Theme ↗️`]( https://typedoc.org/api/classes/Theme.html ) +- [`Theme`](https://typedoc.org/api/classes/Theme.html) ## Methods @@ -38,7 +38,7 @@ This method can be overridden to provide an alternative theme context. | Parameter | Type | | :------ | :------ | -| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\> | +| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\> | #### Returns @@ -48,7 +48,7 @@ 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 )\>[] +> **getUrls**(`project`): [`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[] Maps the models of the given project to the desired output files. @@ -58,11 +58,11 @@ This method can be overriden to provide an alternative url structure. | Parameter | Type | | :------ | :------ | -| `project` | [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) | +| `project` | [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) | #### Returns -[`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\>[] +[`UrlMapping`](/api-docs/Interface.UrlMapping.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\>[] #### Overrides @@ -82,7 +82,7 @@ This method can be overriden to provide an alternative navigation structure. | Parameter | Type | | :------ | :------ | -| `project` | [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) | +| `project` | [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) | #### Returns diff --git a/docs/pages/api-docs/Class.MarkdownThemeContext.md b/docs/pages/api-docs/Class.MarkdownThemeContext.md index 1ed8dcb34..747790ce5 100644 --- a/docs/pages/api-docs/Class.MarkdownThemeContext.md +++ b/docs/pages/api-docs/Class.MarkdownThemeContext.md @@ -27,8 +27,8 @@ class MyMarkdownTheme extends MarkdownTheme { | Parameter | Type | Description | | :------ | :------ | :------ | | `theme` | [`MarkdownTheme`](/api-docs/Class.MarkdownTheme.md) | The theme instance. | -| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\> | The current page event. | -| `options` | [`Options ↗️`]( https://typedoc.org/api/classes/Configuration.Options.html ) | The options provided to the application. | +| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\> | The current page event. | +| `options` | [`Options`](https://typedoc.org/api/classes/Configuration.Options.html) | The options provided to the application. | #### Returns @@ -38,41 +38,35 @@ class MyMarkdownTheme extends MarkdownTheme { Properties are passed into the constructor and are used to provide context to the theme. -### page - -> `readonly` **page**: [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html )\> +### internationalization -The current page event. +> **internationalization**: `Internationalization` *** -### options - -> `readonly` **options**: [`Options ↗️`]( https://typedoc.org/api/classes/Configuration.Options.html ) +### i18n -The options provided to the application. +> **i18n**: `TranslationProxy` -## Methods +*** -General context aware helper methods not bound to any specific models that can be used by the theme resources. +### page -### getText() +> `readonly` **page**: [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html)\> -> **getText**(`key`): `string` +The current page event. -Get text mappings from the theme. +*** -#### Parameters +### options -| Parameter | Type | Description | -| :------ | :------ | :------ | -| `key` | keyof [`TextContentMappings`](/api-docs/Interface.TextContentMappings.md) | The key of the text mappings | +> `readonly` **options**: [`Options`](https://typedoc.org/api/classes/Configuration.Options.html) -#### Returns +The options provided to the application. -`string` +## Methods -*** +General context aware helper methods not bound to any specific models that can be used by the theme resources. ### getPackageMetaData() @@ -102,7 +96,7 @@ If public path is set, it will be used as the base URL. #### Parameters -| Parameter | Type | Default value | Description | +| Parameter | Type | Default Value | Description | | :------ | :------ | :------ | :------ | | `url` | `string` | `undefined` | The URL to make relative. | | `ignorePublicPath` | `boolean` | `false` | Whether to ignore the public path. | @@ -123,32 +117,66 @@ Then `templates` namespace holds the main templates for the theme and are mapped All templates return a string that is passed back to the renderer. Internally templates call partials and helpers. +#### document() + +> **document**: (`page`) => `string` + +Template that maps to a project document. + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<`DocumentReflection`\> | + +##### Returns + +`string` + #### project() -> **project**: () => `string` +> **project**: (`page`) => `string` Template that maps to the root project reflection. This will be the index page / documentation root page. +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html)\> | + ##### Returns `string` #### readme() -> **readme**: () => `string` +> **readme**: (`page`) => `string` Template that specifically maps to the resolved readme file. This template is not used when 'readme' is set to 'none'. +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html)\> | + ##### Returns `string` #### reflection() -> **reflection**: () => `string` +> **reflection**: (`page`) => `string` Template that maps to individual reflection models. +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `page` | [`MarkdownPageEvent`](/api-docs/Class.MarkdownPageEvent.md)\<[`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)\> | + ##### Returns `string` @@ -209,7 +237,7 @@ Partials are categorised by their use: | Parameter | Type | | :------ | :------ | -| `model` | [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) | +| `model` | [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) | ###### Returns @@ -233,7 +261,7 @@ Partials are categorised by their use: | Parameter | Type | | :------ | :------ | -| `model` | [`ContainerReflection ↗️`]( https://typedoc.org/api/classes/Models.ContainerReflection.html ) | +| `model` | [`ContainerReflection`](https://typedoc.org/api/classes/Models.ContainerReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -251,7 +279,7 @@ Renders a collection of reflection categories. | Parameter | Type | | :------ | :------ | -| `model` | [`ReflectionCategory ↗️`]( https://typedoc.org/api/types/Models.ReflectionCategory.html )[] | +| `model` | [`ReflectionCategory`](https://typedoc.org/api/types/Models.ReflectionCategory.html)[] | | `options` | `object` | | `options.headingLevel` | `number` | @@ -269,7 +297,7 @@ Renders a collection of reflection groups. | Parameter | Type | | :------ | :------ | -| `model` | [`ReflectionGroup ↗️`]( https://typedoc.org/api/classes/Models.ReflectionGroup.html )[] | +| `model` | [`ReflectionGroup`](https://typedoc.org/api/classes/Models.ReflectionGroup.html)[] | | `options` | `object` | | `options.headingLevel` | `number` | @@ -287,7 +315,7 @@ Renders a collection of members. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] | | `options` | `object` | | `options.headingLevel` | `number` | @@ -307,7 +335,7 @@ Renders an accessor member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -325,9 +353,26 @@ Renders an constructor member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | +| `options` | `object` | +| `options.headingLevel` | `number` | + +###### Returns + +`string` + +##### memberContainer() + +> **memberContainer**: (`model`, `options`) => `string` + +###### Parameters + +| Parameter | Type | +| :------ | :------ | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | +| `options.nested`? | `boolean` | ###### Returns @@ -343,7 +388,7 @@ Renders a standard declaration member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | | `options.nested`? | `boolean` | @@ -356,13 +401,27 @@ Renders a standard declaration member. > **declarationTitle**: (`model`) => `string` -Remders a declaration title. +###### Parameters + +| Parameter | Type | +| :------ | :------ | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | + +###### Returns + +`string` + +##### documents() + +> **documents**: (`model`, `options`) => `string` ###### Parameters | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) \| [`ContainerReflection`](https://typedoc.org/api/classes/Models.ContainerReflection.html) \| [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) | +| `options` | `object` | +| `options.headingLevel` | `number` | ###### Returns @@ -378,7 +437,7 @@ Renders enum members as a table. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] | ###### Returns @@ -392,7 +451,7 @@ Renders enum members as a table. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationHierarchy ↗️`]( https://typedoc.org/api/classes/Models.DeclarationHierarchy.html ) | +| `model` | [`DeclarationHierarchy`](https://typedoc.org/api/classes/Models.DeclarationHierarchy.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -410,7 +469,7 @@ Renders an index signature block | Parameter | Type | | :------ | :------ | -| `model` | [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html ) | +| `model` | [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | ###### Returns @@ -426,7 +485,7 @@ Renders an inheritance section. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) \| [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) \| [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -444,7 +503,7 @@ Renders the main member title. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | ###### Returns @@ -460,7 +519,7 @@ Renders a top-level member that contains group and child members such as Classes | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -476,7 +535,7 @@ Renders a top-level member that contains group and child members such as Classes | Parameter | Type | | :------ | :------ | -| `model` | [`ParameterReflection ↗️`]( https://typedoc.org/api/classes/Models.ParameterReflection.html )[] | +| `model` | [`ParameterReflection`](https://typedoc.org/api/classes/Models.ParameterReflection.html)[] | ###### Returns @@ -490,7 +549,7 @@ Renders a top-level member that contains group and child members such as Classes | Parameter | Type | | :------ | :------ | -| `model` | [`ParameterReflection ↗️`]( https://typedoc.org/api/classes/Models.ParameterReflection.html )[] | +| `model` | [`ParameterReflection`](https://typedoc.org/api/classes/Models.ParameterReflection.html)[] | ###### Returns @@ -508,7 +567,7 @@ There is no association list partial for properties as these are handled as a st | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] | | `options`? | `object` | | `options.isEventProps`? | `boolean` | @@ -526,7 +585,7 @@ Renders an reference member. | Parameter | Type | | :------ | :------ | -| `model` | [`ReferenceReflection ↗️`]( https://typedoc.org/api/classes/Models.ReferenceReflection.html ) | +| `model` | [`ReferenceReflection`](https://typedoc.org/api/classes/Models.ReferenceReflection.html) | ###### Returns @@ -542,7 +601,7 @@ Renders the flags of a reflection. | Parameter | Type | | :------ | :------ | -| `model` | [`Reflection ↗️`]( https://typedoc.org/api/classes/Models.Reflection.html ) | +| `model` | [`Reflection`](https://typedoc.org/api/classes/Models.Reflection.html) | ###### Returns @@ -552,13 +611,11 @@ Renders the flags of a reflection. > **reflectionIndex**: (`model`, `options`) => `string` -Renders the index section of a reflection. - ###### Parameters | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) \| [`ProjectReflection ↗️`]( https://typedoc.org/api/classes/Models.ProjectReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) \| [`ProjectReflection`](https://typedoc.org/api/classes/Models.ProjectReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -576,11 +633,12 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html ) | +| `model` | [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | | `options.nested`? | `boolean` | | `options.accessor`? | `string` | +| `options.multipleSignatures`? | `boolean` | ###### Returns @@ -594,7 +652,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`ParameterReflection ↗️`]( https://typedoc.org/api/classes/Models.ParameterReflection.html )[] | +| `model` | [`ParameterReflection`](https://typedoc.org/api/classes/Models.ParameterReflection.html)[] | ###### Returns @@ -608,7 +666,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html ) | +| `model` | [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -624,7 +682,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html ) | +| `model` | [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | | `options`? | `object` | | `options.accessor`? | `string` | | `options.includeType`? | `boolean` | @@ -633,6 +691,25 @@ Renders a signature member. `string` +##### signatures() + +> **signatures**: (`model`, `options`) => `string` + +Renders a signature collection. + +###### Parameters + +| Parameter | Type | +| :------ | :------ | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | +| `options` | `object` | +| `options.headingLevel` | `number` | +| `options.nested`? | `boolean` | + +###### Returns + +`string` + ##### sources() > **sources**: (`model`, `options`) => `string` @@ -641,7 +718,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) \| [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) \| [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | @@ -657,7 +734,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | | `options` | `object` | | `options.headingLevel` | `number` | | `options.nested`? | `boolean` | @@ -674,7 +751,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`ReferenceType ↗️`]( https://typedoc.org/api/classes/Models.ReferenceType.html ) \| [`ArrayType ↗️`]( https://typedoc.org/api/types/Models.ArrayType.html ) | +| `model` | [`ReferenceType`](https://typedoc.org/api/classes/Models.ReferenceType.html) \| [`ArrayType`](https://typedoc.org/api/types/Models.ArrayType.html) | ###### Returns @@ -688,7 +765,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`SomeType ↗️`]( https://typedoc.org/api/classes/Models.SomeType.html )[] | +| `model` | [`SomeType`](https://typedoc.org/api/classes/Models.SomeType.html)[] | | `options`? | `object` | | `options.foreCollpase`? | `boolean` | @@ -704,7 +781,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] | | `options` | `object` | | `options.headingLevel` | `number` | @@ -720,7 +797,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] | | `headingLevel` | `number` | ###### Returns @@ -735,7 +812,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] | ###### Returns @@ -749,7 +826,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`TypeParameterReflection ↗️`]( https://typedoc.org/api/classes/Models.TypeParameterReflection.html )[] | +| `model` | [`TypeParameterReflection`](https://typedoc.org/api/classes/Models.TypeParameterReflection.html)[] | ###### Returns @@ -763,7 +840,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`TypeParameterReflection ↗️`]( https://typedoc.org/api/classes/Models.TypeParameterReflection.html )[] | +| `model` | [`TypeParameterReflection`](https://typedoc.org/api/classes/Models.TypeParameterReflection.html)[] | ###### Returns @@ -779,7 +856,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`Comment ↗️`]( https://typedoc.org/api/types/Models.Comment.html ) | +| `model` | [`Comment`](https://typedoc.org/api/types/Models.Comment.html) | | `options` | `object` | | `options.headingLevel`? | `number` | | `options.showSummary`? | `boolean` | @@ -798,7 +875,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`CommentDisplayPart ↗️`]( https://typedoc.org/api/types/Models.CommentDisplayPart.html )[] | +| `model` | [`CommentDisplayPart`](https://typedoc.org/api/types/Models.CommentDisplayPart.html)[] | ###### Returns @@ -814,7 +891,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`ArrayType ↗️`]( https://typedoc.org/api/types/Models.ArrayType.html ) | +| `model` | [`ArrayType`](https://typedoc.org/api/types/Models.ArrayType.html) | ###### Returns @@ -828,7 +905,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`ConditionalType ↗️`]( https://typedoc.org/api/types/Models.ConditionalType.html ) | +| `model` | [`ConditionalType`](https://typedoc.org/api/types/Models.ConditionalType.html) | ###### Returns @@ -842,7 +919,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`IndexedAccessType ↗️`]( https://typedoc.org/api/types/Models.IndexedAccessType.html ) | +| `model` | [`IndexedAccessType`](https://typedoc.org/api/types/Models.IndexedAccessType.html) | ###### Returns @@ -856,7 +933,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`InferredType ↗️`]( https://typedoc.org/api/types/Models.InferredType.html ) | +| `model` | [`InferredType`](https://typedoc.org/api/types/Models.InferredType.html) | ###### Returns @@ -870,7 +947,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`IntersectionType ↗️`]( https://typedoc.org/api/types/Models.IntersectionType.html ) | +| `model` | [`IntersectionType`](https://typedoc.org/api/types/Models.IntersectionType.html) | ###### Returns @@ -884,7 +961,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`IntrinsicType ↗️`]( https://typedoc.org/api/types/Models.IntrinsicType.html ) | +| `model` | [`IntrinsicType`](https://typedoc.org/api/types/Models.IntrinsicType.html) | ###### Returns @@ -898,7 +975,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`LiteralType ↗️`]( https://typedoc.org/api/types/Models.LiteralType.html ) | +| `model` | [`LiteralType`](https://typedoc.org/api/types/Models.LiteralType.html) | ###### Returns @@ -912,7 +989,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`NamedTupleMember ↗️`]( https://typedoc.org/api/types/Models.NamedTupleMember.html ) | +| `model` | [`NamedTupleMember`](https://typedoc.org/api/types/Models.NamedTupleMember.html) | ###### Returns @@ -926,7 +1003,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`QueryType ↗️`]( https://typedoc.org/api/types/Models.QueryType.html ) | +| `model` | [`QueryType`](https://typedoc.org/api/types/Models.QueryType.html) | ###### Returns @@ -940,7 +1017,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`ReferenceType ↗️`]( https://typedoc.org/api/classes/Models.ReferenceType.html ) | +| `model` | [`ReferenceType`](https://typedoc.org/api/classes/Models.ReferenceType.html) | ###### Returns @@ -954,7 +1031,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | ###### Returns @@ -968,7 +1045,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html )[] | +| `model` | [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html)[] | | `options`? | `object` | | `options.forceParameterType`? | `boolean` | @@ -984,7 +1061,7 @@ Renders a signature member. | Parameter | Type | | :------ | :------ | -| `model` | [`ReflectionType ↗️`]( https://typedoc.org/api/classes/Models.ReflectionType.html ) | +| `model` | [`ReflectionType`](https://typedoc.org/api/classes/Models.ReflectionType.html) | | `options`? | `object` | | `options.foreCollpase`? | `boolean` | @@ -1002,7 +1079,7 @@ Takes a generic Type and returns the appropriate partial for it. | Parameter | Type | | :------ | :------ | -| `model`? | [`SomeType ↗️`]( https://typedoc.org/api/classes/Models.SomeType.html ) | +| `model`? | [`SomeType`](https://typedoc.org/api/classes/Models.SomeType.html) | ###### Returns @@ -1016,7 +1093,7 @@ Takes a generic Type and returns the appropriate partial for it. | Parameter | Type | | :------ | :------ | -| `model` | [`TupleType ↗️`]( https://typedoc.org/api/classes/Models.TupleType.html ) | +| `model` | [`TupleType`](https://typedoc.org/api/classes/Models.TupleType.html) | ###### Returns @@ -1030,7 +1107,7 @@ Takes a generic Type and returns the appropriate partial for it. | Parameter | Type | | :------ | :------ | -| `model` | [`TypeOperatorType ↗️`]( https://typedoc.org/api/interfaces/TypeOperatorType.html ) | +| `model` | [`TypeOperatorType`](https://typedoc.org/api/interfaces/TypeOperatorType.html) | ###### Returns @@ -1044,7 +1121,7 @@ Takes a generic Type and returns the appropriate partial for it. | Parameter | Type | | :------ | :------ | -| `model` | [`UnionType ↗️`]( https://typedoc.org/api/types/Models.UnionType.html ) | +| `model` | [`UnionType`](https://typedoc.org/api/types/Models.UnionType.html) | ###### Returns @@ -1058,7 +1135,7 @@ Takes a generic Type and returns the appropriate partial for it. | Parameter | Type | | :------ | :------ | -| `model` | [`UnknownType ↗️`]( https://typedoc.org/api/types/Models.UnknownType.html ) | +| `model` | [`UnknownType`](https://typedoc.org/api/types/Models.UnknownType.html) | ###### Returns @@ -1078,49 +1155,91 @@ Please note that partials: - Can reference other helpers but should not reference partials. - Can return strings or other models. -#### getDeclarationComment() +#### getDeclarationType() -> **getDeclarationComment**: (`model`) => `any` +> **getDeclarationType**: (`model`) => `undefined` \| [`SomeType`](https://typedoc.org/api/classes/Models.SomeType.html) ##### Parameters | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | ##### Returns -`any` +`undefined` \| [`SomeType`](https://typedoc.org/api/classes/Models.SomeType.html) -#### getDeclarationType() +#### getDescriptionForReflection() -> **getDeclarationType**: (`model`) => `undefined` \| [`SomeType ↗️`]( https://typedoc.org/api/classes/Models.SomeType.html ) +> **getDescriptionForReflection**: (`model`) => `null` \| `string` ##### Parameters | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | ##### Returns -`undefined` \| [`SomeType ↗️`]( https://typedoc.org/api/classes/Models.SomeType.html ) +`null` \| `string` #### getFlattenedDeclarations() -> **getFlattenedDeclarations**: (`model`, `options`?) => [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] +> **getFlattenedDeclarations**: (`model`, `options`?) => [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] ##### Parameters | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] | | `options`? | `object` | | `options.includeSignatures`? | `boolean` | ##### Returns -[`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html )[] +[`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] + +#### getGroupIndexList() + +> **getGroupIndexList**: (`children`) => `string` + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `children` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] \| `DocumentReflection`[] | + +##### Returns + +`string` + +#### getGroupIndexTable() + +> **getGroupIndexTable**: (`children`) => `string` + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `children` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html)[] \| `DocumentReflection`[] | + +##### Returns + +`string` + +#### getGroupIndex() + +> **getGroupIndex**: (`group`) => `any` + +##### Parameters + +| Parameter | Type | +| :------ | :------ | +| `group` | [`ReflectionCategory`](https://typedoc.org/api/types/Models.ReflectionCategory.html) \| [`ReflectionGroup`](https://typedoc.org/api/classes/Models.ReflectionGroup.html) | + +##### Returns + +`any` #### getHierarchyType() @@ -1130,7 +1249,7 @@ Please note that partials: | Parameter | Type | | :------ | :------ | -| `model` | [`SomeType ↗️`]( https://typedoc.org/api/classes/Models.SomeType.html ) | +| `model` | [`SomeType`](https://typedoc.org/api/classes/Models.SomeType.html) | | `options`? | `object` | | `options.isTarget`? | `boolean` | @@ -1146,7 +1265,7 @@ Please note that partials: | Parameter | Type | | :------ | :------ | -| `model` | [`ReflectionKind ↗️`]( https://typedoc.org/api/enums/Models.ReflectionKind-1.html ) | +| `model` | [`ReflectionKind`](https://typedoc.org/api/enums/Models.ReflectionKind-1.html) | ##### Returns @@ -1160,7 +1279,7 @@ Please note that partials: | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | ##### Returns @@ -1174,7 +1293,7 @@ Please note that partials: | Parameter | Type | | :------ | :------ | -| `model` | [`ParameterReflection ↗️`]( https://typedoc.org/api/classes/Models.ParameterReflection.html ) | +| `model` | [`ParameterReflection`](https://typedoc.org/api/classes/Models.ParameterReflection.html) | ##### Returns @@ -1188,7 +1307,7 @@ Please note that partials: | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) | ##### Returns @@ -1202,7 +1321,7 @@ Please note that partials: | Parameter | Type | | :------ | :------ | -| `model`? | [`SomeType ↗️`]( https://typedoc.org/api/classes/Models.SomeType.html ) | +| `model`? | [`SomeType`](https://typedoc.org/api/classes/Models.SomeType.html) | ##### Returns @@ -1216,7 +1335,7 @@ Please note that partials: | Parameter | Type | | :------ | :------ | -| `model` | [`DeclarationReflection ↗️`]( https://typedoc.org/api/classes/Models.DeclarationReflection.html ) \| [`SignatureReflection ↗️`]( https://typedoc.org/api/classes/Models.SignatureReflection.html ) | +| `model` | [`DeclarationReflection`](https://typedoc.org/api/classes/Models.DeclarationReflection.html) \| [`SignatureReflection`](https://typedoc.org/api/classes/Models.SignatureReflection.html) | ##### Returns diff --git a/docs/pages/api-docs/Interface.MarkdownApplication.md b/docs/pages/api-docs/Interface.MarkdownApplication.md index d4d5aa87d..3f324c939 100644 --- a/docs/pages/api-docs/Interface.MarkdownApplication.md +++ b/docs/pages/api-docs/Interface.MarkdownApplication.md @@ -16,7 +16,7 @@ export function load(app: MarkdownApplication) { ## Extends -- [`Application ↗️`]( https://typedoc.org/api/classes/Application.html ) +- [`Application`](https://typedoc.org/api/classes/Application.html) ## Properties diff --git a/docs/pages/api-docs/Interface.MarkdownRenderer.md b/docs/pages/api-docs/Interface.MarkdownRenderer.md index 31464eb2c..e9421444f 100644 --- a/docs/pages/api-docs/Interface.MarkdownRenderer.md +++ b/docs/pages/api-docs/Interface.MarkdownRenderer.md @@ -28,13 +28,13 @@ app.renderer.postRenderAsyncJobs.push(async (event) => { ## Extends -- [`Renderer ↗️`]( https://typedoc.org/api/classes/Renderer.html ) +- [`Renderer`](https://typedoc.org/api/classes/Renderer.html) ## Properties ### markdownHooks -> **markdownHooks**: [`EventHooks ↗️`]( https://typedoc.org/api/classes/EventHooks.html )\<[`MarkdownRendererHooks`](/api-docs/Interface.MarkdownRendererHooks.md), `string`\> +> **markdownHooks**: [`EventHooks`](https://typedoc.org/api/classes/EventHooks.html)\<[`MarkdownRendererHooks`](/api-docs/Interface.MarkdownRendererHooks.md), `string`\> *** diff --git a/docs/pages/api-docs/Interface.MarkdownRendererHooks.md b/docs/pages/api-docs/Interface.MarkdownRendererHooks.md index 37fcdc1c2..ffd0553f5 100644 --- a/docs/pages/api-docs/Interface.MarkdownRendererHooks.md +++ b/docs/pages/api-docs/Interface.MarkdownRendererHooks.md @@ -4,7 +4,7 @@ Describes the hooks available to inject output in the markdown theme. ## Usage -```ts + ```ts app.renderer.markdownHooks.on( 'page.end', () => `**Generated using \`page.end\` hook**`, diff --git a/docs/pages/api-docs/Interface.NavigationItem.md b/docs/pages/api-docs/Interface.NavigationItem.md index a51c95060..86a501cbc 100644 --- a/docs/pages/api-docs/Interface.NavigationItem.md +++ b/docs/pages/api-docs/Interface.NavigationItem.md @@ -18,7 +18,7 @@ The model used to define the navigation structure. ### kind? -> `optional` **kind**: [`ReflectionKind ↗️`]( https://typedoc.org/api/enums/Models.ReflectionKind-1.html ) +> `optional` **kind**: [`ReflectionKind`](https://typedoc.org/api/enums/Models.ReflectionKind-1.html) *** diff --git a/docs/pages/api-docs/Interface.PackageMetaData.md b/docs/pages/api-docs/Interface.PackageMetaData.md index 9313ffde8..b6881a56c 100644 --- a/docs/pages/api-docs/Interface.PackageMetaData.md +++ b/docs/pages/api-docs/Interface.PackageMetaData.md @@ -12,4 +12,4 @@ The model used to define the package metadata when in packages mode. ### options -> **options**: [`Options ↗️`]( https://typedoc.org/api/classes/Configuration.Options.html ) +> **options**: [`Options`](https://typedoc.org/api/classes/Configuration.Options.html) diff --git a/docs/pages/api-docs/Interface.PluginOptions.md b/docs/pages/api-docs/Interface.PluginOptions.md index 73a36308f..f632d1038 100644 --- a/docs/pages/api-docs/Interface.PluginOptions.md +++ b/docs/pages/api-docs/Interface.PluginOptions.md @@ -30,17 +30,19 @@ The name of a module that should act as the root page for the documentation. ### enumMembersFormat -> **enumMembersFormat**: `"table"` \| `"list"` +> **enumMembersFormat**: `"table"` \| `"list"` \| `"htmlTable"` Specify the render style of enumeration members. *** -### excludeGroups +### ~~excludeGroups~~ > **excludeGroups**: `boolean` -Excludes grouping by kind so all members are rendered and sorted at the same level. +#### Deprecated + +This option has been renamed hideGroupHeadings to better reflect its purpose. *** @@ -92,6 +94,14 @@ Do not print breadcrumbs. *** +### hideGroupHeadings + +> **hideGroupHeadings**: `boolean` + +Excludes grouping by kind so all members are rendered and sorted at the same level. + +*** + ### hidePageHeader > **hidePageHeader**: `boolean` @@ -110,12 +120,28 @@ Do not print page title. ### indexFormat -> **indexFormat**: `"table"` \| `"list"` +> **indexFormat**: `"table"` \| `"list"` \| `"htmlTable"` 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"`)[] @@ -162,7 +188,7 @@ Determines how output files are generated. ### parametersFormat -> **parametersFormat**: `"table"` \| `"list"` +> **parametersFormat**: `"table"` \| `"list"` \| `"htmlTable"` Specify the render style of parameter and type parameter groups. @@ -178,7 +204,7 @@ Preserve anchor casing when generating link to symbols. ### propertiesFormat -> **propertiesFormat**: `"table"` \| `"list"` +> **propertiesFormat**: `"table"` \| `"list"` \| `"htmlTable"` Specify the render style of property groups for interfaces and classes. @@ -200,9 +226,39 @@ Sanitize HTML and JSX inside JsDoc comments. *** -### textContentMappings +### tableColumnVisibility + +> **tableColumnVisibility**: `object` + +Control header alignment and column visibility in tables. + +#### hideDefaults + +> **hideDefaults**: `boolean` + +#### hideInherited + +> **hideInherited**: `boolean` + +#### hideModifiers + +> **hideModifiers**: `boolean` + +#### hideOverrides + +> **hideOverrides**: `boolean` + +#### hideSources + +> **hideSources**: `boolean` + +*** + +### ~~textContentMappings~~ + +> **textContentMappings**: `Partial`\<`any`\> -> **textContentMappings**: `Partial`\<[`TextContentMappings`](/api-docs/Interface.TextContentMappings.md)\> +#### Deprecated Provides a mechanism to change the content of text used in documentation. @@ -210,7 +266,7 @@ Provides a mechanism to change the content of text used in documentation. ### typeDeclarationFormat -> **typeDeclarationFormat**: `"table"` \| `"list"` +> **typeDeclarationFormat**: `"table"` \| `"list"` \| `"htmlTable"` Specify the render style for type declaration members. diff --git a/docs/pages/api-docs/Interface.TextContentMappings.md b/docs/pages/api-docs/Interface.TextContentMappings.md deleted file mode 100644 index b2272117a..000000000 --- a/docs/pages/api-docs/Interface.TextContentMappings.md +++ /dev/null @@ -1,399 +0,0 @@ -# TextContentMappings - -Describes the keys available to replace static text. - -## Properties - -### header.title - -> **header.title**: `string` - -*** - -### header.docs - -> **header.docs**: `string` - -*** - -### breadcrumbs.home - -> **breadcrumbs.home**: `string` - -*** - -### footer.text - -> **footer.text**: `string` - -*** - -### title.indexPage - -> **title.indexPage**: `string` - -*** - -### title.modulePage - -> **title.modulePage**: `string` - -*** - -### title.memberPage - -> **title.memberPage**: `string` - -*** - -### label.apiIndex - -> **label.apiIndex**: `string` - -*** - -### label.defaultValue - -> **label.defaultValue**: `string` - -*** - -### label.description - -> **label.description**: `string` - -*** - -### label.extendedBy - -> **label.extendedBy**: `string` - -*** - -### label.extends - -> **label.extends**: `string` - -*** - -### label.flags - -> **label.flags**: `string` - -*** - -### label.globals - -> **label.globals**: `string` - -*** - -### label.implements - -> **label.implements**: `string` - -*** - -### label.implementationOf - -> **label.implementationOf**: `string` - -*** - -### label.inheritedFrom - -> **label.inheritedFrom**: `string` - -*** - -### label.index - -> **label.index**: `string` - -*** - -### label.indexable - -> **label.indexable**: `string` - -*** - -### label.indexSignature - -> **label.indexSignature**: `string` - -*** - -### label.member - -> **label.member**: `string` - -*** - -### label.modifier - -> **label.modifier**: `string` - -*** - -### label.name - -> **label.name**: `string` - -*** - -### label.overrides - -> **label.overrides**: `string` - -*** - -### label.packages - -> **label.packages**: `string` - -*** - -### label.reExports - -> **label.reExports**: `string` - -*** - -### label.renamesAndReExports - -> **label.renamesAndReExports**: `string` - -*** - -### label.returns - -> **label.returns**: `string` - -*** - -### label.source - -> **label.source**: `string` - -*** - -### label.type - -> **label.type**: `string` - -*** - -### label.typeDeclaration - -> **label.typeDeclaration**: `string` - -*** - -### label.value - -> **label.value**: `string` - -*** - -### kind.accessor.singular - -> **kind.accessor.singular**: `string` - -*** - -### kind.accessor.plural - -> **kind.accessor.plural**: `string` - -*** - -### kind.class.singular - -> **kind.class.singular**: `string` - -*** - -### kind.class.plural - -> **kind.class.plural**: `string` - -*** - -### kind.constructor.singular - -> **kind.constructor.singular**: `string` - -*** - -### kind.constructor.plural - -> **kind.constructor.plural**: `string` - -*** - -### kind.enum.singular - -> **kind.enum.singular**: `string` - -*** - -### kind.enum.plural - -> **kind.enum.plural**: `string` - -*** - -### kind.enumMember.singular - -> **kind.enumMember.singular**: `string` - -*** - -### kind.enumMember.plural - -> **kind.enumMember.plural**: `string` - -*** - -### kind.event.singular - -> **kind.event.singular**: `string` - -*** - -### kind.event.plural - -> **kind.event.plural**: `string` - -*** - -### kind.function.singular - -> **kind.function.singular**: `string` - -*** - -### kind.function.plural - -> **kind.function.plural**: `string` - -*** - -### kind.interface.singular - -> **kind.interface.singular**: `string` - -*** - -### kind.interface.plural - -> **kind.interface.plural**: `string` - -*** - -### kind.method.singular - -> **kind.method.singular**: `string` - -*** - -### kind.method.plural - -> **kind.method.plural**: `string` - -*** - -### kind.module.singular - -> **kind.module.singular**: `string` - -*** - -### kind.module.plural - -> **kind.module.plural**: `string` - -*** - -### kind.namespace.singular - -> **kind.namespace.singular**: `string` - -*** - -### kind.namespace.plural - -> **kind.namespace.plural**: `string` - -*** - -### kind.variable.singular - -> **kind.variable.singular**: `string` - -*** - -### kind.variable.plural - -> **kind.variable.plural**: `string` - -*** - -### kind.parameter.singular - -> **kind.parameter.singular**: `string` - -*** - -### kind.parameter.plural - -> **kind.parameter.plural**: `string` - -*** - -### kind.property.singular - -> **kind.property.singular**: `string` - -*** - -### kind.property.plural - -> **kind.property.plural**: `string` - -*** - -### kind.reference.singular - -> **kind.reference.singular**: `string` - -*** - -### kind.reference.plural - -> **kind.reference.plural**: `string` - -*** - -### kind.typeAlias.singular - -> **kind.typeAlias.singular**: `string` - -*** - -### kind.typeAlias.plural - -> **kind.typeAlias.plural**: `string` - -*** - -### kind.typeParameter.singular - -> **kind.typeParameter.singular**: `string` - -*** - -### kind.typeParameter.plural - -> **kind.typeParameter.plural**: `string` diff --git a/docs/pages/api-docs/_meta.js b/docs/pages/api-docs/_meta.js index bcfb2aae4..6913acee0 100644 --- a/docs/pages/api-docs/_meta.js +++ b/docs/pages/api-docs/_meta.js @@ -22,6 +22,5 @@ export default { "type": "separator", "title": "Options" }, - "Interface.PluginOptions": "PluginOptions", - "Interface.TextContentMappings": "TextContentMappings" + "Interface.PluginOptions": "PluginOptions" } \ No newline at end of file diff --git a/docs/pages/api-docs/index.mdx b/docs/pages/api-docs/index.md similarity index 94% rename from docs/pages/api-docs/index.mdx rename to docs/pages/api-docs/index.md index 40d6bb8bb..7feb4a0c5 100644 --- a/docs/pages/api-docs/index.mdx +++ b/docs/pages/api-docs/index.md @@ -35,4 +35,3 @@ Types that are used to define the plugin options. | Member | Description | | :------ | :------ | | [PluginOptions](/api-docs/Interface.PluginOptions.md) | Describes the options declared by the plugin. | -| [TextContentMappings](/api-docs/Interface.TextContentMappings.md) | Describes the keys available to replace static text. | diff --git a/docs/pages/docs/CHANGELOG.md b/docs/pages/docs/CHANGELOG.md new file mode 100644 index 000000000..6236b6380 --- /dev/null +++ b/docs/pages/docs/CHANGELOG.md @@ -0,0 +1,126 @@ +# 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 a2ee53a74..f4a8d0752 100644 --- a/docs/pages/docs/_meta.js +++ b/docs/pages/docs/_meta.js @@ -12,10 +12,11 @@ export default { }, 'typedoc-usage': '', 'customizing-output': '', - navigation: '', '-- Support': { type: 'separator', title: 'Support', }, + versioning: '', + CHANGELOG: '', 'migration-guide': 'Migration Guide V4', }; diff --git a/docs/pages/docs/customizing-output.mdx b/docs/pages/docs/customizing-output.mdx index 2b57dc2c2..7291fd1a2 100644 --- a/docs/pages/docs/customizing-output.mdx +++ b/docs/pages/docs/customizing-output.mdx @@ -146,3 +146,7 @@ Use my new helper - ${this.helpers.newHelper()} ``` Please see the [Custom Theme API](/api-docs#custom-theme) for more information. + +## Navigation + +If required, a navigation model can be provided to the output by utilizing the [--navigationModel](/docs/options/utility-options#--navigationmodel) option. diff --git a/docs/pages/docs/navigation.mdx b/docs/pages/docs/navigation.mdx deleted file mode 100644 index eccf694fc..000000000 --- a/docs/pages/docs/navigation.mdx +++ /dev/null @@ -1,30 +0,0 @@ -# Navigation - -If required, a navigation model can be provided to the output. This is useful if you want to provide a custom sidebar/navigation implementation (if relevant to your environment). - -## Usage - -The navigation model can be accessed by utilizing the `postRenderAsyncJobs` on the renderer. - -The navigation is returned as `JSON` and can be mapped to a custom structure and written to a file. - -The model can be configured by the [`--navigationModel`](/docs/options#navigationmodel) option. - -```ts filename="custom-plugin.mjs" -// @ts-check - -import { MarkdownApplication } from 'typedoc-plugin-markdown'; - -/** - * @param {import('typedoc-plugin-markdown').MarkdownApplication} app - */ -export function load(app) { - app.renderer.postRenderAsyncJobs.push(async (renderer) => { - // The navigation JSON structure is available on the navigation object. - const navigation = renderer.navigation; - - // This can be parsed to something else or written straight to a file: - fs.writeFileSync('navigation.json', JSON.stringify(navigation)); - }); -} -``` diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx index 635d21a51..100d4968e 100644 --- a/docs/pages/docs/options.mdx +++ b/docs/pages/docs/options.mdx @@ -2,697 +2,52 @@ import { Callout, FileTree } from "nextra/components"; # Options -These options should be used in conjunction with core TypeDoc options (see [TypeDoc Usage](/docs/typedoc-usage)). - -## Output Options - -### outputFileStrategy - -Determines how output files are generated. - -> Accepts either `"members"` or `"modules"`. Defaults to `"members"`. - -TypeDoc creates documentation according to exports derived from the given [`entryPointsStrategy`](https://typedoc.org/options/input/#entrypointstrategy) configuration. - -This option does not alter the way TypeDoc interprets the `entryPointsStrategy` but rather provides some flexibility as to how output files are generated. - -It is also possible to further refine what members are exported to individual files with the [`membersWithOwnFile`](#memberswithownfile) option. - -The following keys are available: - -**members** - -Generates an individual file for each exported module member. This is the standard behaviour of the HTML theme and the plugin default. - - - - - - - - - - - - - - - - - - - - - -**modules** - -Generates a single file for every Module or Namespace where all members are hoisted to a single module file. This creates a flat navigation structure and reduces the amount of files generated. - - - - - - - -```json filename="typedoc.json" -{ - "outputFileStrategy": "members" -} -``` - ---- - -### membersWithOwnFile - - - Determines which members are exported to their own file when - `outputFileStrategy` equals `members`. - - -> Accepts an array of the following values `"Enum"` `"Variable"` `"Function"` `"Class"` `"Interface"` `"TypeAlias"`. - -This option is useful when only specific types of members should be exported to a single file. - -Ignored when [`outputFileStrategy`](#outputfilestrategy) is equal to `"modules"` - -```json filename="typedoc.json" -{ - "membersWithOwnFile": ["Class", "Enum", "Interface"] -} -``` - ---- - -### flattenOutputFiles - -Flatten output files to a single directory. - -> Accepts a boolean value. Defaults to `false`. - -By default output files are generated in a directory structure that mirrors the project's module hierarchy including folders for member kinds eg `classes`, `enums`, `functions` etc. - -This option will flatten the output files to a single directory as follows: - -Default output: - - - - - - - - - - - - - - - -Flattened output: - - - - - - - - - -```json filename="typedoc.json" -{ - "flattenOutputFiles": false -} -``` - ---- - -### fileExtension - - - Specify the file extension for generated output files. - - -> Accepts a string value. Defaults to `".md"`. - -Typically markdown files are recognised by the `.md` or `.markdown` file extensions.`.mdx` maybe required for compatibility with certain markdown parsers. - -```json filename="typedoc.json" -{ - "fileExtension": ".mdx" -} -``` - ---- - -### entryFileName - -The file name of the entry page. - -> Accepts a string value. Defaults to `"README"`. - -The entry page is the root page of the documentation, equivalent to `index.html` for web pages. - -`README` is recognised when browsing folders on repos and Wikis and is the plugin default. `index` might be more suitable for static site generators. - -The content of this file will be resolved in the following order: - -1. The value of the [`entryModule`](#entrymodule) option (if defined). -2. The resolved Readme file (skipped if the [`readme`](https://typedoc.org/options/input/#readme) option is set to `none`). -3. The documentation index page. - -```json filename="typedoc.json" -{ - "entryFileName": "index" -} -``` - ---- - -### entryModule - - - The name of a module that should act as the root page for the documentation. - - -> Accepts a string value. Defaults to `"undefined"`. - -This option can be used when the root page of the documentation should be a specific module (typically a module named `index`). - -The module name should be specified (NOT the reference to the file name). - -Please note a separate modules index page will not be generated, therefore would work better if navigation is present. - -```json filename="typedoc.json" -{ - "entryModule": "index" -} -``` - ---- - -### mergeReadme - - - Merges the resolved readme into the project index page. - - -> 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. - -This option has no effect when [`readme`](https://typedoc.org/options/input/#readme) is set to `"none"`. - -```json filename="typedoc.json" -{ - "mergeReadme": false -} -``` - ---- - -### excludeScopesInPaths - -Exclude writing @ scope directories in paths. - -> Accepts a boolean value. Defaults to `false`. - -By default directories are split by scopes when generating file paths. - -This option will remove reference to `@scope` in the path when generating files and directories. It does not affect the name of the package or module in the output. - -The following will be the directory structure for packages named `@scope/package-1` and `@scope/package-2`: - -`false` (default): - -{" "} - - - - - - - -`true`: - - - - - - -Ignored if `flattenOutputFiles` is set to `true`. - -```json filename="typedoc.json" -{ - "excludeScopesInPaths": false -} -``` - ---- - -## UX Options - -### hidePageHeader - -Do not print page header. - -> Accepts a boolean value. Defaults to `false`. - -```json filename="typedoc.json" -{ - "hidePageHeader": false -} -``` - ---- - -### hidePageTitle - -Do not print page title. - -> Accepts a boolean value. Defaults to `false`. - -```json filename="typedoc.json" -{ - "hidePageTitle": false -} -``` - ---- - -### hideBreadcrumbs - -Do not print breadcrumbs. - -> Accepts a boolean value. Defaults to `false`. - -```json filename="typedoc.json" -{ - "hideBreadcrumbs": false -} -``` - ---- - -### inlineDocuments - -Inline documents in pages. - -> Accepts a boolean value. Defaults to `false`. - -By default a documents index and separate documents pages are generated when using the `@document` tag. - -```json filename="typedoc.json" -{ - "inlineDocuments": false -} -``` - ---- - -### excludeGroups - - - Excludes grouping by kind so all members are rendered and sorted at the same - level. - - -> Accepts a boolean value. Defaults to `false`. - -By default members are grouped by kind (eg Classes, Functions etc). - -This creates a flat structure where all members are displayed at the same heading level. - -```json filename="typedoc.json" -{ - "excludeGroups": false -} -``` - ---- - -### useCodeBlocks - -Wraps signatures and declarations in code blocks. - -> Accepts a boolean value. Defaults to `false`. - -This option can be used to improve readability and aesthetics when defining signatures and declarations. - -Please note that when this option is set to `true` it is not possible to link to other references. - -As a work around the [`@link`](https://typedoc.org/tags/link/) tag can be be used to manually reference types. - -```json filename="typedoc.json" -{ - "useCodeBlocks": false -} -``` - ---- - -### expandObjects - -Expand objects inside declarations. - -> Accepts a boolean value. Defaults to `false`. - -By default objects inside declarations are collapsed to preserve space and improve readability. - -This option should be set when a full object representation is preferred. - -**Default** - -`object` - -**Expanded** - -\{ `"x"`: `string` } - -```json filename="typedoc.json" -{ - "expandObjects": false -} -``` - ---- - -### expandParameters - - - Expand parameters in signature parentheses to display type information. - - -> Accepts a boolean value. Defaults to `false`. - -By default parameters in signature definitions only display the parameter name so the output is more concise. - -This option should be set when a full type representation is preferred. - -**Default** - -`someFunction(param1, param2)` - -**Expanded** - -`someFunction(param1: string, param2: boolean)` - -```json filename="typedoc.json" -{ - "expandParameters": false -} -``` - ---- - -### parametersFormat - - - Specify the render style of parameter and type parameter groups. - - -> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. - -This option either renders parameters for functions and class methods as a list or in tabular format. - -```json filename="typedoc.json" -{ - "parametersFormat": "list" -} -``` - ---- - -### propertiesFormat - - - Specify the render style of property groups for interfaces and classes. - - -> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. - -This option either renders properties for classes and interfaces as a list or in tabular format. - -```json filename="typedoc.json" -{ - "propertiesFormat": "list" -} -``` - ---- - -### enumMembersFormat - -Specify the render style of enumeration members. - -> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. - -This option either renders members of enums as a list or in tabular format. - -```json filename="typedoc.json" -{ - "enumMembersFormat": "list" -} -``` - ---- - -### typeDeclarationFormat - - - Specify the render style for type declaration members. - - -> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. - -This option either renders type declarations as a list or in tabular format. - -```json filename="typedoc.json" -{ - "typeDeclarationFormat": "list" -} -``` - ---- - -### indexFormat - -Specify the render format for index items. - -> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. - -This option renders index items either as a simple list or in a table with a description column exposing the comment summary. - -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). - -```json filename="typedoc.json" -{ - "indexFormat": "list" -} -``` - ---- - -### tableColumns - - - Control header alignment and column visibility in tables. - - -> - -By default, all available data for symbols are displayed in columns, which can result in very large tables. - -This option allows you to control the visibility of columns, prioritizing readability over displaying complete data. - -```json filename="typedoc.json" -{ - "tableColumns": { - "excludeDefaultsCol": false, - "excludeInheritedFromCol": false, - "excludeModifiersCol": false, - "excludeOverridesCol": false, - "excludeSourcesCol": false, - "leftAlignHeadings": false - } -} -``` - ---- - -### textContentMappings - - - Provides a mechanism to change the content of text used in documentation. - - -> Accepts a key/value object. - - - **Please note TypeDoc 0.26 will be introducing a native i18n implementation. - This option will likely be deprecated in favour of utilizing the native - implementation when 0.26 is released.** - - -This option enables changing static text rendered to the documentation. -Useful if an alternative English phrase is preferred or to translate English text to another language. -This option does not attempt to address translating text within code comments. - -**Placeholders** - -Default values within curly braces `{}` indicates a placeholder of dynamic text. -The `{version}` placeholder requires the TypeDoc option [`includeVersion`](https://typedoc.org/options/input/#includeversion) to be true. - -**Keys** - -Keys are categorised with the following namespace conventions: - -- `header.*`, `breadcrumbs.*`,`footer.*`: Text in main page elements (if displayed). -- `title.*`: Text in main page titles. -- `label.*` Text in page content, including content headings and table headers. -- `kind.*` Text mappings to TypeDoc's `ReflectionKind` definitions. - -Only keys that require translation need to be added to the object. - -```json filename="typedoc.json" -{ - "textContentMappings": {} -} -``` - ---- + + These options should be used in conjunction with the core TypeDoc options (see + [TypeDoc Usage](/docs/typedoc-usage)). + + +## File Options + +Options that are used to configure how files are output. + +- [--outputFileStrategy](./options/file-options.mdx#--outputfilestrategy) +- [--membersWithOwnFile](./options/file-options.mdx#--memberswithownfile) +- [--flattenOutputFiles](./options/file-options.mdx#--flattenoutputfiles) +- [--fileExtension](./options/file-options.mdx#--fileextension) +- [--entryFileName](./options/file-options.mdx#--entryfilename) +- [--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 + +Options that are used to configure how the output is structured and displayed . + +- [--hidePageHeader](./options/display-options.mdx#--hidepageheader) +- [--hidePageTitle](./options/display-options.mdx#--hidepagetitle) +- [--hideBreadcrumbs](./options/display-options.mdx#--hidebreadcrumbs) +- [--hideGroupHeadings](./options/display-options.mdx#--hidegroupheadings) +- [--useCodeBlocks](./options/display-options.mdx#--usecodeblocks) +- [--expandObjects](./options/display-options.mdx#--expandobjects) +- [--expandParameters](./options/display-options.mdx#--expandparameters) +- [--parametersFormat](./options/display-options.mdx#--parametersformat) +- [--propertiesFormat](./options/display-options.mdx#--propertiesformat) +- [--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) ## Utility Options -### publicPath - -Specify the base path for all urls. - -> Accepts a string value. Defaults to `"undefined"`. - -If undefined all urls will be relative. - -```json filename="typedoc.json" -{ - "publicPath": "http://abc.com" -} -``` - ---- - -### sanitizeComments - -Sanitize HTML and JSX inside JsDoc comments. - -> Accepts a boolean value. Defaults to `false`. - -_Please note this options does not affect the rendering of inline code or code blocks (using single/triple backticks)._ - -By default all comments written inside JsDoc comments will be passed to the output as written, and parsers will interpret un-escaped angle brackets as HTML/JSX tags.. - -This option will escape angle brackets `<` `>` and curly braces `{` `}` written inside JsDoc comments. - -This option would typically be used when source code comes from an external library exposing the following potential issues: - -- Comments contain raw tags that should be interpreted as code examples. -- Comments contain invalid syntax that (in the case of MDX) will cause breaking parsing errors. -- Although most parsers use XSS filters, this option provides an additional layer of XSS security. - -```json filename="typedoc.json" -{ - "sanitizeComments": false -} -``` - ---- - -### anchorPrefix - - - Custom anchor prefix when anchoring to in-page symbols. - - -> Accepts a string value. Defaults to `"undefined"`. - -This option should be used when parsers require a custom anchor prefix. - -```json filename="typedoc.json" -{ - "anchorPrefix": "markdown-header" -} -``` - ---- - -### useHTMLAnchors - -Add HTML named anchors to headings and table rows. - -> Accepts a boolean value. Defaults to `false`. - -This option should be used if there are issues with anchoring to symbols within a page. - -- For markdown parsers that do not automatically assign header ids. -- When cross referencing symbols that are referenced in a table row. - -```json filename="typedoc.json" -{ - "useHTMLAnchors": false -} -``` - ---- - -### preserveAnchorCasing - - - Preserve anchor casing when generating link to symbols. - - -> Accepts a boolean value. Defaults to `false`. - -By default references to symbol anchor links are lowercased. - -This option can be used for engines that require the preservation of anchor link casing. - -```json filename="typedoc.json" -{ - "preserveAnchorCasing": false -} -``` - ---- - -### navigationModel - - - Configures how the navigation model will be generated. - - -> - -By default navigation is not written to file but can be consumed programmatically. Please see [Navigation Guide](/docs/navigation) for more information. - -`navigationModel.excludeGroups` - -Do not organise navigation by groups. - -`navigationModel.excludeCategories` - -Do not organise navigation by categories. - -`navigationModel.excludeFolders` - -Excludes unnecessary nesting with complex modules/namespace hierarchies. - -```json filename="typedoc.json" -{ - "navigationModel": { - "excludeGroups": false, - "excludeCategories": false, - "excludeFolders": false - } -} -``` +Options that are used for general configuration and utility purposes. ---- +- [--publicPath](./options/utility-options.mdx#--publicpath) +- [--sanitizeComments](./options/utility-options.mdx#--sanitizecomments) +- [--anchorPrefix](./options/utility-options.mdx#--anchorprefix) +- [--useHTMLAnchors](./options/utility-options.mdx#--usehtmlanchors) +- [--preserveAnchorCasing](./options/utility-options.mdx#--preserveanchorcasing) +- [--navigationModel](./options/utility-options.mdx#--navigationmodel) +- [~--textContentMappings~](./options/utility-options.mdx#--textcontentmappings) diff --git a/docs/pages/docs/options/_meta.js b/docs/pages/docs/options/_meta.js new file mode 100644 index 000000000..85bc7a149 --- /dev/null +++ b/docs/pages/docs/options/_meta.js @@ -0,0 +1,5 @@ +export default { + "file-options": "", + "display-options": "", + "utility-options": "", +}; diff --git a/docs/pages/docs/options/display-options.mdx b/docs/pages/docs/options/display-options.mdx new file mode 100644 index 000000000..742534d8b --- /dev/null +++ b/docs/pages/docs/options/display-options.mdx @@ -0,0 +1,244 @@ +import { Callout, FileTree } from "nextra/components"; + +# Display Options + +## --hidePageHeader + +Do not print page header. + +> Accepts a boolean value. Defaults to `false`. + +```json filename="typedoc.json" +{ + "hidePageHeader": false +} +``` + +## --hidePageTitle + +Do not print page title. + +> Accepts a boolean value. Defaults to `false`. + +```json filename="typedoc.json" +{ + "hidePageTitle": false +} +``` + +## --hideBreadcrumbs + +Do not print breadcrumbs. + +> Accepts a boolean value. Defaults to `false`. + +```json filename="typedoc.json" +{ + "hideBreadcrumbs": false +} +``` + +## --hideGroupHeadings + + + Excludes grouping by kind so all members are rendered and sorted at the same + level. + + +> Accepts a boolean value. Defaults to `false`. + +By default members are grouped by kind (eg Classes, Functions etc). + +This creates a flat structure where all members are displayed at the same heading level. + +```json filename="typedoc.json" +{ + "hideGroupHeadings": false +} +``` + +## --useCodeBlocks + +Wraps signatures and declarations in code blocks. + +> Accepts a boolean value. Defaults to `false`. + +This option can be used to improve readability and aesthetics when defining signatures and declarations. + +Please note that when this option is set to `true` it is not possible to link to other references. + +As a work around the [`@link`](https://typedoc.org/tags/link/) tag can be be used to manually reference types. + +```json filename="typedoc.json" +{ + "useCodeBlocks": false +} +``` + +## --expandObjects + +Expand objects inside declarations. + +> Accepts a boolean value. Defaults to `false`. + +By default objects inside declarations are collapsed to preserve space and improve readability. + +This option should be set when a full object representation is preferred. + +```json filename="typedoc.json" +{ + "expandObjects": false +} +``` + +## --expandParameters + + + Expand parameters in signature parentheses to display type information. + + +> Accepts a boolean value. Defaults to `false`. + +By default parameters in signature definitions only display the parameter name so the output is more concise. + +This option should be set when a full type representation is preferred. + +```json filename="typedoc.json" +{ + "expandParameters": false +} +``` + +## --parametersFormat + + + Specify the render style of parameter and type parameter groups. + + +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. + +This option specifies the output format for parameters and type parameters of functions and class methods: + +- **"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. + +```json filename="typedoc.json" +{ + "parametersFormat": "list" +} +``` + +## --propertiesFormat + + + Specify the render style of property groups for interfaces and classes. + + +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. + +This option specifies the output format for class and interface properties: + +- **"list"**: properties are output in linear blocks with headings, suitable for more detailed comments. +- **"table"**: properties are output within a markdown table, condensed into a single paragraph. +- **"htmlTable"**: properties are output in an HTML table, enabling block elements to render in tabular format. + +```json filename="typedoc.json" +{ + "propertiesFormat": "list" +} +``` + +## --enumMembersFormat + +Specify the render style of enumeration members. + +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. + +This option specifies the output format for enumeration members: + +- **"list"**: members are output in linear blocks with headings, suitable for more detailed comments. +- **"table"**: members are output within a markdown table, condensed into a single paragraph. +- **"htmlTable"**: members are output in an HTML table, enabling block elements to render in tabular format. + +```json filename="typedoc.json" +{ + "enumMembersFormat": "list" +} +``` + +## --typeDeclarationFormat + + + Specify the render style for type declaration members. + + +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. + +This option specifies the output format for type declaration: + +- **"list"**: declarations are output in linear blocks with headings, suitable for more detailed comments. +- **"table"**: declarations are output within a markdown table, condensed into a single paragraph. +- **"htmlTable"**: declarations are output in an HTML table, enabling block elements to render in tabular format. + +```json filename="typedoc.json" +{ + "typeDeclarationFormat": "list" +} +``` + +## --indexFormat + +Specify the render format for index items. + +> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`. + +This option renders index items either as a simple list or in a table with a description column exposing the comment summary. + +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). + +```json filename="typedoc.json" +{ + "indexFormat": "list" +} +``` + +## --tableColumnVisibility + + + Control header alignment and column visibility in tables. + + +> + +By default, all available data for symbols are displayed in table columns. + +This option allows you to control the visibility of columns, prioritizing readability over displaying complete data. + +```json filename="typedoc.json" +{ + "tableColumnVisibility": { + "hideDefaults": false, + "hideInherited": false, + "hideModifiers": false, + "hideOverrides": false, + "hideSources": 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 new file mode 100644 index 000000000..9e6ce2aca --- /dev/null +++ b/docs/pages/docs/options/file-options.mdx @@ -0,0 +1,240 @@ +import { Callout, FileTree } from "nextra/components"; + +# File Options + +## --outputFileStrategy + +Determines how output files are generated. + +> Accepts either `"members"` or `"modules"`. Defaults to `"members"`. + +TypeDoc creates documentation according to exports derived from the given [`entryPointsStrategy`](https://typedoc.org/options/input/#entrypointstrategy) configuration. + +This option does not alter the way TypeDoc interprets the `entryPointsStrategy` but rather provides some flexibility as to how output files are generated. + +It is also possible to further refine what members are exported to individual files with the [`membersWithOwnFile`](#memberswithownfile) option. + +The following keys are available: + +- **"members":** generates an individual file for each exported module member. This is the standard behavior of the HTML theme and the default setting of the plugin. + + + + + + + + + + + + + + + + + + + + + +- **"modules"**: generates a single file for every Module or Namespace where all members are hoisted to a single module file. This creates a flat navigation structure and reduces the amount of files generated. + + + + + + +```json filename="typedoc.json" +{ + "outputFileStrategy": "members" +} +``` + +## --membersWithOwnFile + + + Determines which members are exported to their own file when + `outputFileStrategy` equals `members`. + + +> Accepts an array of the following values `"Enum"` `"Variable"` `"Function"` `"Class"` `"Interface"` `"TypeAlias"`. + +This option is useful when only specific types of members should be exported to a single file. + +Ignored when [`outputFileStrategy`](#outputfilestrategy) is equal to `"modules"` + +```json filename="typedoc.json" +{ + "membersWithOwnFile": ["Class", "Enum", "Interface"] +} +``` + +## --flattenOutputFiles + +Flatten output files to a single directory. + +> Accepts a boolean value. Defaults to `false`. + +By default output files are generated in a directory structure that mirrors the project's module hierarchy including folders for member kinds eg `classes`, `enums`, `functions` etc. + +This option will flatten the output files to a single directory as follows: + +**Default output:** + + + + + + + + + + + + + + + +**Flattened output:** + + + + + + + + + +```json filename="typedoc.json" +{ + "flattenOutputFiles": false +} +``` + +## --fileExtension + + + Specify the file extension for generated output files. + + +> Accepts a string value. Defaults to `".md"`. + +Typically markdown files are recognised by the `.md` or `.markdown` file extensions.`.mdx` maybe required for compatibility with certain markdown parsers. + +```json filename="typedoc.json" +{ + "fileExtension": ".mdx" +} +``` + +## --entryFileName + +The file name of the entry page. + +> Accepts a string value. Defaults to `"README"`. + +The entry page is the root page of the documentation, equivalent to `index.html` for web pages. + +`README` is recognised when browsing folders on repos and Wikis and is the plugin default. `index` might be more suitable for static site generators. + +The content of this file will be resolved in the following order: + +1. The value of the [`entryModule`](#entrymodule) option (if defined). +2. The resolved Readme file (skipped if the [`readme`](https://typedoc.org/options/input/#readme) option is set to `none`). +3. The documentation index page. + +```json filename="typedoc.json" +{ + "entryFileName": "index" +} +``` + +## --entryModule + + + The name of a module that should act as the root page for the documentation. + + +> Accepts a string value. Defaults to `"undefined"`. + +This option can be used when the root page of the documentation should be a specific module (typically a module named `index`). + +The module name should be specified (NOT the reference to the file name). + +Please note a separate modules index page will not be generated, therefore would work better if navigation is present. + +```json filename="typedoc.json" +{ + "entryModule": "index" +} +``` + +## --excludeScopesInPaths + +Exclude writing @ scope directories in paths. + +> Accepts a boolean value. Defaults to `false`. + +By default directories are split by scopes when generating file paths. + +This option will remove reference to `@scope` in the path when generating files and directories. It does not affect the name of the package or module in the output. + +The following will be the directory structure for packages named `@scope/package-1` and `@scope/package-2`: + +- **`false`** + + + + + + + + +- **`true`** + + + + + +Ignored if `flattenOutputFiles` is set to `true`. + +```json filename="typedoc.json" +{ + "excludeScopesInPaths": false +} +``` + +## --mergeReadme + + + Merges the resolved readme into the project index page. + + +> 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. + +This option has no effect when [`readme`](https://typedoc.org/options/input/#readme) is set to `"none"`. + +```json filename="typedoc.json" +{ + "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 new file mode 100644 index 000000000..2b9ced3e9 --- /dev/null +++ b/docs/pages/docs/options/utility-options.mdx @@ -0,0 +1,152 @@ +import { Callout, FileTree } from "nextra/components"; + +# Utility Options + +## --publicPath + +Specify the base path for all urls. + +> Accepts a string value. Defaults to `"undefined"`. + +If undefined all urls will be relative. + +```json filename="typedoc.json" +{ + "publicPath": "http://abc.com" +} +``` + +## --sanitizeComments + +Sanitize HTML and JSX inside JsDoc comments. + +> Accepts a boolean value. Defaults to `false`. + +_Please note this options does not affect the rendering of inline code or code blocks (using single/triple backticks)._ + +By default all comments written inside JsDoc comments will be passed to the output as written, and parsers will interpret un-escaped angle brackets as HTML/JSX tags.. + +This option will escape angle brackets `<` `>` and curly braces `{` `}` written inside JsDoc comments. + +This option would typically be used when source code comes from an external library exposing the following potential issues: + +- Comments contain raw tags that should be interpreted as code examples. +- Comments contain invalid syntax that (in the case of MDX) will cause breaking parsing errors. +- Although most parsers use XSS filters, this option provides an additional layer of XSS security. + +```json filename="typedoc.json" +{ + "sanitizeComments": false +} +``` + +## --anchorPrefix + + + Custom anchor prefix when anchoring to in-page symbols. + + +> Accepts a string value. Defaults to `"undefined"`. + +This option should be used when parsers require a custom anchor prefix. + +```json filename="typedoc.json" +{ + "anchorPrefix": "markdown-header" +} +``` + +## --useHTMLAnchors + +Add HTML named anchors to headings and table rows. + +> Accepts a boolean value. Defaults to `false`. + +This option should be used if there are issues with anchoring to symbols within a page. + +- For markdown parsers that do not automatically assign header ids. +- When cross referencing symbols that are referenced in a table row. + +```json filename="typedoc.json" +{ + "useHTMLAnchors": false +} +``` + +## --preserveAnchorCasing + + + Preserve anchor casing when generating link to symbols. + + +> Accepts a boolean value. Defaults to `false`. + +By default references to symbol anchor links are lowercased. + +This option can be used for engines that require the preservation of anchor link casing. + +```json filename="typedoc.json" +{ + "preserveAnchorCasing": false +} +``` + +## --navigationModel + + + Configures how the navigation model will be generated. + + +> + +By default navigation is not written to file but can be consumed programmatically. +This is useful if you want to provide a custom sidebar/navigation implementation (if relevant to your environment). + +The navigation model can be accessed by utilizing the `postRenderAsyncJobs` on the renderer. + +The navigation is returned as `JSON` and can be mapped to a custom structure and written to a file. + +- `navigationModel.excludeGroups`: do not organise navigation by groups. +- `navigationModel.excludeCategories`: do not organise navigation by categories. +- `navigationModel.excludeFolders`: excludes unnecessary nesting with complex hierarchies. + +```ts filename="custom-plugin.ts" +import { MarkdownApplication } from "typedoc-plugin-markdown"; + +export function load(app: MarkdownApplication) { + app.renderer.postRenderAsyncJobs.push(async (renderer) => { + // The navigation JSON structure is available on the navigation object. + const navigation = renderer.navigation; + + // This can be parsed to something else or written straight to a file: + fs.writeFileSync("navigation.json", JSON.stringify(navigation)); + }); +} +``` + +```json filename="typedoc.json" +{ + "navigationModel": { + "excludeGroups": false, + "excludeCategories": false, + "excludeFolders": false + } +} +``` + +## ~--textContentMappings~ + + + Deprecated: This option has been deprecated in favour of TypeDoc's 0.26 + localization feature. + + +> Accepts a key/value object. + +This option enables changing static text rendered to the documentation. + +```json filename="typedoc.json" +{ + "textContentMappings": {} +} +``` diff --git a/docs/pages/docs/versioning.mdx b/docs/pages/docs/versioning.mdx new file mode 100644 index 000000000..03c3a1c75 --- /dev/null +++ b/docs/pages/docs/versioning.mdx @@ -0,0 +1,35 @@ +# Versioning + +This page should help you understand the versioning rules of the plugin and its compatibility with TypeDoc. + +## Versioning Rules + +Please note that TypeDoc is still released within the 0.x.x range and may include breaking changes within each minor version release. + +For this reason we follow a slightly amended version of semver: + +- **Patch** versions will include all bug fixes but might also include non-breaking new features. +- **Minor** versions will be released in sync with TypeDoc minor versions and will include any necessary API and feature changes to support the new TypeDoc version and features. + Any option changes will attempt to be made in a backwards compatible manor. +- **Major** versions will be made if significant and breaking changes to the plugin are made. + +## Compatibility Table + +| typedoc-plugin-markdown | TypeDoc | Release Date | +| ----------------------- | ------- | ------------ | +| 4.1.x | 0.26.x | 2024-06-21 | +| 4.0.x | 0.25.x | 2024-05-03 | + +## Specifying Version Ranges + +You may prefer to fix versions or use a tilde (~) when declaring `typedoc-plugin-markdown` and `TypeDoc` versions in your `package.json` file. +The tilde allows only patch updates within the specified minor version. + +```json filename="package.json" +{ + "devDependencies": { + "typedoc": "~0.26.0", + "typedoc-plugin-markdown": "~4.1.0" + } +} +``` diff --git a/docs/pages/plugins/docusaurus/options.mdx b/docs/pages/plugins/docusaurus/options.mdx index 3ec77a0ef..ff6aef716 100644 --- a/docs/pages/plugins/docusaurus/options.mdx +++ b/docs/pages/plugins/docusaurus/options.mdx @@ -24,7 +24,7 @@ The following are preset typedoc-plugin-markdown options: The following options are exposed by this plugin: -### sidebar +## --sidebar Configures the autogenerated Docusaurus sidebar. @@ -48,5 +48,3 @@ Please see the [sidebar guide](/plugins/docusaurus/guide/sidebar) for additional } } ``` - ---- diff --git a/docs/pages/plugins/frontmatter/options.mdx b/docs/pages/plugins/frontmatter/options.mdx index e9ed04080..2a2efbe5e 100644 --- a/docs/pages/plugins/frontmatter/options.mdx +++ b/docs/pages/plugins/frontmatter/options.mdx @@ -2,7 +2,7 @@ import { Callout, FileTree } from "nextra/components"; # Options -## frontmatterGlobals +## --frontmatterGlobals Specify static variables to be added to all frontmatter blocks. @@ -26,9 +26,7 @@ sidebar: true } ``` ---- - -## readmeFrontmatter +## --readmeFrontmatter Specify static variables to be added to the readme page only. @@ -44,9 +42,7 @@ sidebar: true } ``` ---- - -## indexFrontmatter +## --indexFrontmatter Specify static variables to be added to the index page only. @@ -62,9 +58,7 @@ sidebar: true } ``` ---- - -## frontmatterCommentTags +## --frontmatterCommentTags Specify which comment block tags should be added to frontmatter. @@ -97,9 +91,7 @@ description: A description that will be added to frontmatter. } ``` ---- - -## preserveFrontmatterCommentTags +## --preserveFrontmatterCommentTags Preserve tags defined in frontmatter block tags in output. @@ -113,9 +105,7 @@ description: A description that will be added to frontmatter. } ``` ---- - -## frontmatterNamingConvention +## --frontmatterNamingConvention The naming convention that variables should be output as.{" "} @@ -132,5 +122,3 @@ This option can configure the output style of frontmatter variables when written "frontmatterNamingConvention": "camelCase" } ``` - ---- diff --git a/docs/pages/plugins/github-wiki/options.mdx b/docs/pages/plugins/github-wiki/options.mdx index 202be412a..9ec396155 100644 --- a/docs/pages/plugins/github-wiki/options.mdx +++ b/docs/pages/plugins/github-wiki/options.mdx @@ -23,7 +23,7 @@ The following are preset typedoc-plugin-markdown options: The following options are exposed by this plugin: -### sidebar +## --sidebar Configures the autogenerated `_sidebar.md file`. @@ -45,5 +45,3 @@ The heading displayed above the sidebar. } } ``` - ---- diff --git a/docs/pages/plugins/gitlab-wiki/options.mdx b/docs/pages/plugins/gitlab-wiki/options.mdx index 5f3304961..d333077c9 100644 --- a/docs/pages/plugins/gitlab-wiki/options.mdx +++ b/docs/pages/plugins/gitlab-wiki/options.mdx @@ -22,7 +22,7 @@ The following are preset typedoc-plugin-markdown options: The following options are exposed by this plugin: -### sidebar +## --sidebar Configures the autogenerated `_Sidebar.md file`. @@ -44,5 +44,3 @@ The heading displayed above the sidebar. } } ``` - ---- diff --git a/docs/pages/plugins/remark/options.mdx b/docs/pages/plugins/remark/options.mdx index c0ede1f16..8d509ed3e 100644 --- a/docs/pages/plugins/remark/options.mdx +++ b/docs/pages/plugins/remark/options.mdx @@ -2,7 +2,7 @@ import { Callout, FileTree } from "nextra/components"; # Options -## remarkPlugins +## --remarkPlugins An array of remark plugin names. @@ -27,9 +27,7 @@ Please note options can be passed either as an array of strings or an array of s } ``` ---- - -## remarkStringifyOptions +## --remarkStringifyOptions Custom options for the remark-stringify plugin. @@ -49,5 +47,3 @@ Please see https://github.com/remarkjs/remark/tree/main/packages/remark-stringif } } ``` - ---- diff --git a/docs/pages/plugins/vitepress/options.mdx b/docs/pages/plugins/vitepress/options.mdx index 8957c97cb..7201c522c 100644 --- a/docs/pages/plugins/vitepress/options.mdx +++ b/docs/pages/plugins/vitepress/options.mdx @@ -23,7 +23,7 @@ The following are preset typedoc-plugin-markdown options: The following options are exposed by this plugin: -### docsRoot +## --docsRoot The path to the VitePress project root. @@ -53,9 +53,13 @@ Requires the following config: } ``` ---- +```json filename="typedoc.json" +{ + "docsRoot": "./" +} +``` -### sidebar +## --sidebar Configures the autogenerated VitePress sidebar. @@ -89,5 +93,3 @@ Pretty format the sidebar JSON. } } ``` - ---- diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx index e31352286..49139e8f3 100644 --- a/docs/theme.config.jsx +++ b/docs/theme.config.jsx @@ -35,8 +35,8 @@ export default { content: ( <> 🎉{' '} - - V4 Released • Find out more! + + v4.1 released • Find out more! ), diff --git a/packages/typedoc-plugin-markdown/.docs/typedoc.json b/packages/typedoc-plugin-markdown/.docs/typedoc.json index 3e0990901..baaa0cd61 100644 --- a/packages/typedoc-plugin-markdown/.docs/typedoc.json +++ b/packages/typedoc-plugin-markdown/.docs/typedoc.json @@ -9,8 +9,8 @@ "publicPath": "/api-docs", "indexFormat": "table", "mergeReadme": true, - "fileExtension": ".mdx", - "entryFileName": "index.mdx", + "leftAlignTableHeaders": true, + "entryFileName": "index.md", "hideBreadcrumbs": true, "hidePageHeader": true, "excludeGroups": true, diff --git a/packages/typedoc-plugin-markdown/src/app/application.ts b/packages/typedoc-plugin-markdown/src/app/application.ts index b6e110cf9..9aab428e4 100644 --- a/packages/typedoc-plugin-markdown/src/app/application.ts +++ b/packages/typedoc-plugin-markdown/src/app/application.ts @@ -8,7 +8,7 @@ import { MarkdownRendererHooks } from './renderer/markdown-renderer-hooks'; * * This is essentially a copy of the main class with the `renderer` property overridden to the custom {@link MarkdownRenderer}. * - * @usage + * ## Usage * * ```ts * import {MarkdownApplication} from 'typedoc-plugin-markdown'; @@ -29,7 +29,7 @@ export interface MarkdownApplication extends Application { * * Includes updated typings for hooks and async jobs. * - * @usage + * ## Usage * * ```ts * import { MarkdownApplication } from 'typedoc-plugin-markdown'; 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 77d1456a5..bbe9e2b4e 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 @@ -3,7 +3,7 @@ import { Event, ProjectReflection, Reflection } from 'typedoc'; /** * An event emitted by before and after the markup of a page is rendered. * - * @usage + * ## Usage * * ```ts * export function load(app: MarkdownApplication) { diff --git a/packages/typedoc-plugin-markdown/src/app/events/markdown-renderer-event.ts b/packages/typedoc-plugin-markdown/src/app/events/markdown-renderer-event.ts index 01d8f2763..a58034dca 100644 --- a/packages/typedoc-plugin-markdown/src/app/events/markdown-renderer-event.ts +++ b/packages/typedoc-plugin-markdown/src/app/events/markdown-renderer-event.ts @@ -15,7 +15,7 @@ import { Event, ProjectReflection, Reflection } from 'typedoc'; /** * An event emitted at the beginning and end of the rendering process. * - * @usage + * ## Usage * * ```ts * app.renderer.on(MarkdownRendererEvent.BEGIN, (event) => { diff --git a/packages/typedoc-plugin-markdown/src/app/renderer/markdown-renderer-hooks.ts b/packages/typedoc-plugin-markdown/src/app/renderer/markdown-renderer-hooks.ts index 98a5f2efa..823a80da9 100644 --- a/packages/typedoc-plugin-markdown/src/app/renderer/markdown-renderer-hooks.ts +++ b/packages/typedoc-plugin-markdown/src/app/renderer/markdown-renderer-hooks.ts @@ -3,7 +3,7 @@ import { MarkdownThemeContext } from 'public-api'; /** * Describes the hooks available to inject output in the markdown theme. * - * @usage + * ## Usage * * ```ts * app.renderer.markdownHooks.on( diff --git a/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts b/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts index 5e9f47262..d619d7734 100644 --- a/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts +++ b/packages/typedoc-plugin-markdown/src/defs/typedoc.d.ts @@ -14,10 +14,12 @@ declare module 'typedoc' { fileExtension: string; flattenOutputFiles: boolean; hideBreadcrumbs: boolean; + hideGroupHeadings: boolean; hidePageHeader: boolean; hidePageTitle: boolean; indexFormat: 'list' | 'table' | 'htmlTable'; inlineDocuments: boolean; + leftAlignTableHeaders: boolean; membersWithOwnFile: ( | 'Enum' | 'Variable' @@ -38,13 +40,12 @@ declare module 'typedoc' { propertiesFormat: 'list' | 'table' | 'htmlTable'; publicPath: string; sanitizeComments: boolean; - tableColumns: { - excludeDefaultsCol: boolean; - excludeInheritedFromCol: boolean; - excludeModifiersCol: boolean; - excludeOverridesCol: boolean; - excludeSourcesCol: boolean; - leftAlignHeadings: boolean; + tableColumnVisibility: { + hideDefaults: boolean; + hideInherited: boolean; + hideModifiers: boolean; + hideOverrides: boolean; + hideSources: boolean; }; textContentMappings: ManuallyValidatedOption>; typeDeclarationFormat: 'list' | 'table' | 'htmlTable'; diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts index 19d001f22..614673149 100644 --- a/packages/typedoc-plugin-markdown/src/options/declarations.ts +++ b/packages/typedoc-plugin-markdown/src/options/declarations.ts @@ -15,10 +15,7 @@ import { * * The following keys are available: * - * @members - * - * Generates an individual file for each exported module member. This is the standard behaviour of the HTML theme and the plugin default. - * + * - **"members":** generates an individual file for each exported module member. This is the standard behavior of the HTML theme and the default setting of the plugin. * * * @@ -39,17 +36,14 @@ import { * * * - * @modules - * - * Generates a single file for every Module or Namespace where all members are hoisted to a single module file. This creates a flat navigation structure and reduces the amount of files generated. - * + * - **"modules"**: generates a single file for every Module or Namespace where all members are hoisted to a single module file. This creates a flat navigation structure and reduces the amount of files generated. * * * * * * - * @category Output + * @category File */ export const outputFileStrategy: Partial = { help: 'Determines how output files are generated.', @@ -65,7 +59,7 @@ export const outputFileStrategy: Partial = { * * @example ["Class", "Enum", "Interface"] * - * @category Output + * @category File */ export const membersWithOwnFile: Partial = { help: 'Determines which members are exported to their own file when `outputFileStrategy` equals `members`.', @@ -90,7 +84,7 @@ export const membersWithOwnFile: Partial = { * * This option will flatten the output files to a single directory as follows: * - * Default output: + * **Default output:** * * * @@ -106,7 +100,7 @@ export const membersWithOwnFile: Partial = { * * * - * Flattened output: + * **Flattened output:** * * * @@ -117,7 +111,7 @@ export const membersWithOwnFile: Partial = { * * * - * @category Output + * @category File */ export const flattenOutputFiles: Partial = { help: 'Flatten output files to a single directory.', @@ -130,7 +124,7 @@ export const flattenOutputFiles: Partial = { * * @example ".mdx" * - * @category Output + * @category File */ export const fileExtension: Partial = { help: 'Specify the file extension for generated output files.', @@ -158,7 +152,7 @@ export const fileExtension: Partial = { * * @example "index" * - * @category Output + * @category File * */ export const entryFileName: Partial = { @@ -176,27 +170,13 @@ export const entryFileName: Partial = { * * @example "index" * - * @category Output + * @category File */ export const entryModule: Partial = { help: 'The name of a module that should act as the root page for the documentation.', type: ParameterType.String, }; -/** - * 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. - * - * This option has no effect when [`readme`](https://typedoc.org/options/input/#readme) is set to `"none"`. - * - * @category Output - * - */ -export const mergeReadme: Partial = { - help: 'Merges the resolved readme into the project index page.', - type: ParameterType.Boolean, - defaultValue: false, -}; - /** * By default directories are split by scopes when generating file paths. * @@ -204,17 +184,15 @@ export const mergeReadme: Partial = { * * The following will be the directory structure for packages named `@scope/package-1` and `@scope/package-2`: * - * `false` (default): - * - * + * - **`false`** + * * * * * * * - * `true`: - * + * - **`true`** * * * @@ -222,7 +200,7 @@ export const mergeReadme: Partial = { * * Ignored if `flattenOutputFiles` is set to `true`. * - * @category Output + * @category File */ export const excludeScopesInPaths: Partial = { help: 'Exclude writing @ scope directories in paths.', @@ -231,7 +209,34 @@ export const excludeScopesInPaths: Partial = { }; /** - * @category UX + * 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. + * + * 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.', + type: ParameterType.Boolean, + 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 */ export const hidePageHeader: Partial = { help: 'Do not print page header.', @@ -240,7 +245,7 @@ export const hidePageHeader: Partial = { }; /** - * @category UX + * @category Display */ export const hidePageTitle: Partial = { help: 'Do not print page title.', @@ -249,7 +254,7 @@ export const hidePageTitle: Partial = { }; /** - * @category UX + * @category Display */ export const hideBreadcrumbs: Partial = { help: 'Do not print breadcrumbs.', @@ -258,25 +263,25 @@ export const hideBreadcrumbs: Partial = { }; /** - * By default a documents index and separate documents pages are generated when using the `@document` tag. + * By default members are grouped by kind (eg Classes, Functions etc). + * + * This creates a flat structure where all members are displayed at the same heading level. * - * @category UX + * @category Display */ -export const inlineDocuments: Partial = { - help: 'Inline documents in pages.', +export const hideGroupHeadings: Partial = { + help: 'Excludes grouping by kind so all members are rendered and sorted at the same level.', type: ParameterType.Boolean, defaultValue: false, }; /** - * By default members are grouped by kind (eg Classes, Functions etc). - * - * This creates a flat structure where all members are displayed at the same heading level. + * @deprecated * - * @category UX + * @hidden */ export const excludeGroups: Partial = { - help: 'Excludes grouping by kind so all members are rendered and sorted at the same level.', + help: '@deprecated This option has been renamed hideGroupHeadings to better reflect its purpose.', type: ParameterType.Boolean, defaultValue: false, }; @@ -288,7 +293,7 @@ export const excludeGroups: Partial = { * * As a work around the [`@link`](https://typedoc.org/tags/link/) tag can be be used to manually reference types. * - * @category UX + * @category Display */ export const useCodeBlocks: Partial = { help: 'Wraps signatures and declarations in code blocks.', @@ -301,15 +306,7 @@ export const useCodeBlocks: Partial = { * * This option should be set when a full object representation is preferred. * - * @Default - * - * `object` - * - * @Expanded - * - * \{ `"x"`: `string` } - * - * @category UX + * @category Display */ export const expandObjects: Partial = { help: 'Expand objects inside declarations.', @@ -322,15 +319,7 @@ export const expandObjects: Partial = { * * This option should be set when a full type representation is preferred. * - * @Default - * - * `someFunction(param1, param2)` - * - * @Expanded - * - * `someFunction(param1: string, param2: boolean)` - * - * @category UX + * @category Display */ export const expandParameters: Partial = { help: 'Expand parameters in signature parentheses to display type information.', @@ -339,9 +328,13 @@ export const expandParameters: Partial = { }; /** - * This option either renders parameters for functions and class methods as a list or in tabular format. + * This option specifies the output format for parameters and type parameters of functions and class methods: + * + * - **"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. * - * @category UX + * @category Display */ export const parametersFormat: Partial = { help: 'Specify the render style of parameter and type parameter groups.', @@ -351,10 +344,13 @@ export const parametersFormat: Partial = { }; /** - * This option either renders properties for classes and interfaces as a list or in tabular format. + * This option specifies the output format for class and interface properties: * - * @category UX + * - **"list"**: properties are output in linear blocks with headings, suitable for more detailed comments. + * - **"table"**: properties are output within a markdown table, condensed into a single paragraph. + * - **"htmlTable"**: properties are output in an HTML table, enabling block elements to render in tabular format. * + * @category Display */ export const propertiesFormat: Partial = { help: 'Specify the render style of property groups for interfaces and classes.', @@ -364,9 +360,13 @@ export const propertiesFormat: Partial = { }; /** - * This option either renders members of enums as a list or in tabular format. + * This option specifies the output format for enumeration members: * - * @category UX + * - **"list"**: members are output in linear blocks with headings, suitable for more detailed comments. + * - **"table"**: members are output within a markdown table, condensed into a single paragraph. + * - **"htmlTable"**: members are output in an HTML table, enabling block elements to render in tabular format. + * + * @category Display */ export const enumMembersFormat: Partial = { help: 'Specify the render style of enumeration members.', @@ -376,9 +376,13 @@ export const enumMembersFormat: Partial = { }; /** - * This option either renders type declarations as a list or in tabular format. + * This option specifies the output format for type declaration: + * + * - **"list"**: declarations are output in linear blocks with headings, suitable for more detailed comments. + * - **"table"**: declarations are output within a markdown table, condensed into a single paragraph. + * - **"htmlTable"**: declarations are output in an HTML table, enabling block elements to render in tabular format. * - * @category UX + * @category Display */ export const typeDeclarationFormat: Partial = { help: 'Specify the render style for type declaration members.', @@ -392,7 +396,7 @@ export const typeDeclarationFormat: Partial = { * * 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). * - * @category UX + * @category Display */ export const indexFormat: Partial = { help: 'Specify the render format for index items.', @@ -402,71 +406,35 @@ export const indexFormat: Partial = { }; /** - * By default, all available data for symbols are displayed in columns, which can result in very large tables. + * By default, all available data for symbols are displayed in table columns. * * This option allows you to control the visibility of columns, prioritizing readability over displaying complete data. * - * @category UX + * @category Display */ -export const tableColumns: Partial = { +export const tableColumnVisibility: Partial = { help: 'Control header alignment and column visibility in tables.', type: ParameterType.Flags, defaults: { - excludeDefaultsCol: false, - excludeInheritedFromCol: false, - excludeModifiersCol: false, - excludeOverridesCol: false, - excludeSourcesCol: false, - leftAlignHeadings: false, + hideDefaults: false, + hideInherited: false, + hideModifiers: false, + hideOverrides: false, + hideSources: false, }, }; /** - * - * **Please note TypeDoc 0.26 will be introducing a native i18n implementation. This option will likely be deprecated in favour of utilizing the native implementation when 0.26 is released.** - * - * - * This option enables changing static text rendered to the documentation. - * Useful if an alternative English phrase is preferred or to translate English text to another language. - * This option does not attempt to address translating text within code comments. - * - * **Placeholders** - * - * Default values within curly braces `{}` indicates a placeholder of dynamic text. - * The `{version}` placeholder requires the TypeDoc option [`includeVersion`](https://typedoc.org/options/input/#includeversion) to be true. + * By default table alignment is not specified which means the table headings will typically be centred. * - * **Keys** + * This options can be used to specify left alignment for table headings. * - * Keys are categorised with the following namespace conventions: - * - * - `header.*`, `breadcrumbs.*`,`footer.*`: Text in main page elements (if displayed). - * - `title.*`: Text in main page titles. - * - `label.*` Text in page content, including content headings and table headers. - * - `kind.*` Text mappings to TypeDoc's `ReflectionKind` definitions. - * - * Only keys that require translation need to be added to the object. - * - * @category UX + * @category Display */ -export const textContentMappings: Partial = { - help: 'Provides a mechanism to change the content of text used in documentation.', - type: ParameterType.Mixed, - defaultValue: {}, - 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( - `[typedoc-plugin-markdown] All values of textContentMappings must be strings.`, - ); - } - } - }, +export const leftAlignTableHeaders: Partial = { + help: 'Left aligns items in table headers', + type: ParameterType.Boolean, + defaultValue: false, }; /** @@ -544,19 +512,31 @@ export const preserveAnchorCasing: Partial = { }; /** - * By default navigation is not written to file but can be consumed programmatically. Please see [Navigation Guide](/docs/navigation) for more information. + * By default navigation is not written to file but can be consumed programmatically. + * This is useful if you want to provide a custom sidebar/navigation implementation (if relevant to your environment). + * + * The navigation model can be accessed by utilizing the `postRenderAsyncJobs` on the renderer. * - * `navigationModel.excludeGroups` + * The navigation is returned as `JSON` and can be mapped to a custom structure and written to a file. * - * Do not organise navigation by groups. + * - `navigationModel.excludeGroups`: do not organise navigation by groups. + * - `navigationModel.excludeCategories`: do not organise navigation by categories. + * - `navigationModel.excludeFolders`: excludes unnecessary nesting with complex hierarchies. * - * `navigationModel.excludeCategories` + * ```ts filename="custom-plugin.ts" * - * Do not organise navigation by categories. + * import { MarkdownApplication } from 'typedoc-plugin-markdown'; * - * `navigationModel.excludeFolders` + * export function load(app: MarkdownApplication) { + * app.renderer.postRenderAsyncJobs.push(async (renderer) => { + * // The navigation JSON structure is available on the navigation object. + * const navigation = renderer.navigation; * - * Excludes unnecessary nesting with complex modules/namespace hierarchies. + * // This can be parsed to something else or written straight to a file: + * fs.writeFileSync('navigation.json', JSON.stringify(navigation)); + * }); + * } + * ``` * * @category Utility * @@ -570,3 +550,34 @@ export const navigationModel: Partial = { excludeFolders: false, }, }; + +/** + * + * This option enables changing static text rendered to the documentation. + * + * @deprecated + * + * This option has been deprecated in favour of TypeDoc's 0.26 localization feature. + * + * @category Utility + */ +export const textContentMappings: Partial = { + help: '@deprecated Provides a mechanism to change the content of text used in documentation.', + type: ParameterType.Mixed, + defaultValue: {}, + 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( + `[typedoc-plugin-markdown] All values of textContentMappings must be strings.`, + ); + } + } + }, +}; diff --git a/packages/typedoc-plugin-markdown/src/options/option-types.ts b/packages/typedoc-plugin-markdown/src/options/option-types.ts index adb3f1571..d73ebbdd7 100644 --- a/packages/typedoc-plugin-markdown/src/options/option-types.ts +++ b/packages/typedoc-plugin-markdown/src/options/option-types.ts @@ -27,7 +27,7 @@ export interface PluginOptions { enumMembersFormat: 'list' | 'table' | 'htmlTable'; /** - * Excludes grouping by kind so all members are rendered and sorted at the same level. + * @deprecated This option has been renamed hideGroupHeadings to better reflect its purpose. */ excludeGroups: boolean; @@ -61,6 +61,11 @@ export interface PluginOptions { */ hideBreadcrumbs: boolean; + /** + * Excludes grouping by kind so all members are rendered and sorted at the same level. + */ + hideGroupHeadings: boolean; + /** * Do not print page header. */ @@ -81,6 +86,11 @@ export interface PluginOptions { */ inlineDocuments: boolean; + /** + * Left aligns items in table headers + */ + leftAlignTableHeaders: boolean; + /** * Determines which members are exported to their own file when `outputFileStrategy` equals `members`. */ @@ -140,19 +150,18 @@ export interface PluginOptions { /** * Control header alignment and column visibility in tables. */ - tableColumns: { - excludeDefaultsCol: boolean; - excludeInheritedFromCol: boolean; - excludeModifiersCol: boolean; - excludeOverridesCol: boolean; - excludeSourcesCol: boolean; - leftAlignHeadings: boolean; + tableColumnVisibility: { + hideDefaults: boolean; + hideInherited: boolean; + hideModifiers: boolean; + hideOverrides: boolean; + hideSources: boolean; }; /** - * Provides a mechanism to change the content of text used in documentation. + * @deprecated Provides a mechanism to change the content of text used in documentation. */ - textContentMappings: Partial; + textContentMappings: Partial; /** * Specify the render style for type declaration members. diff --git a/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts b/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts index 96da79b68..65923bf14 100644 --- a/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts +++ b/packages/typedoc-plugin-markdown/src/theme/markdown-theme.ts @@ -25,7 +25,7 @@ import { MarkdownThemeContext } from './markdown-themecontext'; * * The API follows the implementation of [TypeDoc's custom theming](https://github.com/TypeStrong/typedoc/blob/master/internal-docs/custom-themes.md) with some minor adjustments. * - * @usage + * ## Usage * * ```ts * export function load(app) { diff --git a/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts b/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts index 550228026..1f2835ead 100644 --- a/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts +++ b/packages/typedoc-plugin-markdown/src/theme/markdown-themecontext.ts @@ -13,7 +13,7 @@ import { Internationalization, Options, Reflection } from 'typedoc'; * * This class can be used to customize the theme output by extending the class and overriding the [templates](#templates), [partials](#partials) and [helpers](#helpers). * - * @usage + * ## Usage * * ```ts * class MyMarkdownTheme extends MarkdownTheme { 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 dc3a9e01e..4b2cd83de 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,9 +11,10 @@ export function getGroupIndexTable( this: MarkdownThemeContext, children: DeclarationReflection[] | DocumentReflection[], ) { - const tableColumnsOptions = this.options.getValue('tableColumns'); + const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); const headers = [ - this.options.getValue('excludeGroups') + this.options.getValue('excludeGroups') || + this.options.getValue('hideGroupHeadings') ? this.i18n.theme_member() : ReflectionKind.singularString(children[0].kind), this.i18n.theme_description(), @@ -34,5 +35,5 @@ export function getGroupIndexTable( rows.push(row); }); - return table(headers, rows, tableColumnsOptions.leftAlignHeadings); + return table(headers, rows, leftAlignHeadings); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.body.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.body.ts index 9381b48ae..4d0e6e17a 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.body.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/container.body.ts @@ -28,7 +28,8 @@ export function body( ReflectionKind.Namespace, ]; if ( - this.options.getValue('excludeGroups') && + (this.options.getValue('excludeGroups') || + this.options.getValue('hideGroupHeadings')) && containerKinds.includes(model.kind) ) { if (model.categories?.length) { 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 d3ebccacc..620e21500 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,11 +12,15 @@ export function enumMembersTable( this: MarkdownThemeContext, model: DeclarationReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumns'); - + const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); + const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); const comments = model.map((param) => !!param.comment?.hasVisibleComponent()); const hasComments = comments.some((value) => Boolean(value)); + const hasSources = + !tableColumnsOptions.hideSources && + !this.options.getValue('disableSources'); + const headers = [ this.internationalization.kindSingularString(ReflectionKind.EnumMember), this.i18n.theme_value(), @@ -26,6 +30,10 @@ export function enumMembersTable( headers.push(this.i18n.theme_description()); } + if (hasSources) { + headers.push(this.i18n.theme_defined_in()); + } + const rows: string[][] = []; model.forEach((property: DeclarationReflection) => { @@ -55,12 +63,17 @@ export function enumMembersTable( row.push('-'); } } + + if (hasSources) { + row.push(this.partials.sources(property, { headingLevel: -1 })); + } + rows.push(row); }); return this.options.getValue('enumMembersFormat') == 'table' - ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) - : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); + ? table(headers, rows, leftAlignHeadings) + : htmlTable(headers, rows, leftAlignHeadings); } function getComments(property: DeclarationReflection) { 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 a95870e3f..312d23c30 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,7 +10,8 @@ export function parametersTable( this: MarkdownThemeContext, model: ParameterReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumns'); + const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); + const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); const parseParams = (current: any, acc: any) => { const shouldFlatten = @@ -35,7 +36,7 @@ export function parametersTable( }; const showDefaults = - !tableColumnsOptions.excludeDefaultsCol && hasDefaultValues(model); + !tableColumnsOptions.hideDefaults && hasDefaultValues(model); const parsedParams = model.reduce( (acc: any, current: any) => parseParams(current, acc), @@ -103,8 +104,8 @@ export function parametersTable( }); return this.options.getValue('parametersFormat') == 'table' - ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) - : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); + ? table(headers, rows, leftAlignHeadings) + : htmlTable(headers, rows, leftAlignHeadings); } function hasDefaultValues(parameters: ParameterReflection[]) { 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 5a9934065..6664b77fe 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 @@ -22,24 +22,25 @@ export function declarationsTable( model: DeclarationReflection[], options?: { isEventProps: boolean }, ): string { - const tableColumnsOptions = this.options.getValue('tableColumns'); + const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); + const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); const modifiers = model.map((param) => this.helpers.getModifier(param)?.toString(), ); const hasModifiers = - !tableColumnsOptions.excludeModifiersCol && + !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.excludeOverridesCol && + !tableColumnsOptions.hideOverrides && model.some((prop) => Boolean(prop.overwrites)); const hasInheritance = - !tableColumnsOptions.excludeInheritedFromCol && + !tableColumnsOptions.hideInherited && model.some((prop) => Boolean(prop.inheritedFrom)); const hasDefaults = model.some((prop) => @@ -50,7 +51,7 @@ export function declarationsTable( ); const hasSources = - !tableColumnsOptions.excludeSourcesCol && + !tableColumnsOptions.hideSources && !this.options.getValue('disableSources'); const headers: string[] = []; @@ -177,6 +178,6 @@ export function declarationsTable( }); return this.options.getValue('propertiesFormat') == 'table' - ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) - : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); + ? table(headers, rows, leftAlignHeadings) + : htmlTable(headers, rows, leftAlignHeadings); } diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts index 1a0db41ed..078ba49cd 100644 --- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts +++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/member.reflectionIndex.ts @@ -32,7 +32,10 @@ export function reflectionIndex( !(group.owningReflection instanceof DocumentReflection), ); - if (this.options.getValue('excludeGroups')) { + if ( + this.options.getValue('excludeGroups') || + this.options.getValue('hideGroupHeadings') + ) { const children = groups?.reduce((acc, group) => { return [...acc, ...group.children]; }, []); 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 7bd12710e..83c45631e 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,7 +10,12 @@ export function typeDeclarationTable( this: MarkdownThemeContext, model: DeclarationReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumns'); + const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); + const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); + + const hasSources = + !tableColumnsOptions.hideSources && + !this.options.getValue('disableSources'); const headers: string[] = []; @@ -38,6 +43,10 @@ export function typeDeclarationTable( headers.push(this.i18n.theme_description()); } + if (hasSources) { + headers.push(this.i18n.theme_defined_in()); + } + const rows: string[][] = []; declarations.forEach((declaration: DeclarationReflection, index: number) => { @@ -63,10 +72,14 @@ export function typeDeclarationTable( } } + if (hasSources) { + row.push(this.partials.sources(declaration, { headingLevel: -1 })); + } + rows.push(row); }); return this.options.getValue('typeDeclarationFormat') == 'table' - ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) - : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); + ? table(headers, rows, leftAlignHeadings) + : htmlTable(headers, rows, leftAlignHeadings); } 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 0638f4d93..0c2b2de7c 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,10 +9,11 @@ export function typeParametersTable( this: MarkdownThemeContext, model: TypeParameterReflection[], ): string { - const tableColumnsOptions = this.options.getValue('tableColumns'); + const tableColumnsOptions = this.options.getValue('tableColumnVisibility'); + const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); const hasDefault = - !tableColumnsOptions.excludeDefaultsCol && + !tableColumnsOptions.hideDefaults && model.some((typeParameter) => Boolean(typeParameter.default)); const hasComments = model.some((typeParameter) => @@ -69,6 +70,6 @@ export function typeParametersTable( }); return this.options.getValue('parametersFormat') == 'table' - ? table(headers, rows, tableColumnsOptions.leftAlignHeadings) - : htmlTable(headers, rows, tableColumnsOptions.leftAlignHeadings); + ? table(headers, rows, leftAlignHeadings) + : htmlTable(headers, rows, leftAlignHeadings); } 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 52fce11f0..de3576966 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,7 @@ export function packagesIndex( this: MarkdownThemeContext, model: ProjectReflection, ): string { - const tableColumnsOptions = this.options.getValue('tableColumns'); + const leftAlignHeadings = this.options.getValue('leftAlignTableHeaders'); const md: string[] = []; @@ -54,9 +54,7 @@ export function packagesIndex( return rows; }); - md.push( - table(headers, packageRows || [], tableColumnsOptions.leftAlignHeadings), - ); + md.push(table(headers, packageRows || [], leftAlignHeadings)); } else { const packagesList = model.children?.map((projectPackage) => { const urlTo = Boolean(projectPackage.readme) diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts index b244ed018..38b29afb2 100644 --- a/packages/typedoc-plugin-markdown/test/fixtures/config.ts +++ b/packages/typedoc-plugin-markdown/test/fixtures/config.ts @@ -12,10 +12,10 @@ const config: Record = { ], hidePageHeader: true, hideBreadcrumbs: true, - tableColumns: { - excludeSourcesCol: true, - leftAlignHeadings: true, + tableColumnVisibility: { + hideSources: true, }, + leftAlignTableHeaders: true, }, options: [ {}, @@ -43,9 +43,7 @@ const config: Record = { disableSources: true, expandObjects: true, expandParameters: true, - tableColumns: { - leftAlignHeadings: true, - }, + leftAlignTableHeaders: true, }, options: [ {}, @@ -93,9 +91,7 @@ const config: Record = { theme: 'stub-groups', disableSources: true, entryFileName: 'index.md', - tableColumns: { - leftAlignHeadings: true, - }, + leftAlignTableHeaders: true, }, options: [ { @@ -113,7 +109,7 @@ const config: Record = { 'TypeAlias', 'Function', ], - excludeGroups: true, + hideGroupHeadings: true, useHTMLAnchors: true, indexFormat: 'table', categorizeByGroup: false, @@ -124,13 +120,14 @@ const config: Record = { only: false, entryPoints: '/comments/index.ts', commonOptions: { - plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')], + plugin: [ + path.join(__dirname, 'custom-plugins', 'normalize-sources.mjs'), + path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs'), + ], hidePageHeader: true, hideBreadcrumbs: true, readme: 'none', - disableSources: true, inlineDocuments: true, - //media: './test/fixtures/media', }, options: [ { @@ -149,14 +146,14 @@ const config: Record = { parametersFormat: 'htmlTable', propertiesFormat: 'htmlTable', typeDeclarationFormat: 'htmlTable', - tableColumns: { - excludeDefaultsCol: true, - excludeInheritedFromCol: true, - excludeModifiersCol: true, - excludeOverridesCol: true, - excludeSourcesCol: true, - leftAlignHeadings: true, + tableColumnVisibility: { + hideDefaults: true, + hideInherited: true, + hideModifiers: true, + hideOverrides: true, + hideSources: true, }, + leftAlignTableHeaders: true, }, ], }, @@ -168,9 +165,7 @@ const config: Record = { entryPointStrategy: 'packages', name: 'packages-example', disableSources: true, - tableColumns: { - leftAlignHeadings: true, - }, + leftAlignTableHeaders: true, }, options: [ { entryFileName: 'index.md' }, @@ -233,9 +228,7 @@ const config: Record = { commonOptions: { plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')], disableSources: true, - tableColumns: { - leftAlignHeadings: true, - }, + leftAlignTableHeaders: true, }, options: [ { 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 7ef711937..6f8b111f4 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 @@ -116,9 +116,9 @@ exports[`Comments should get tables for emum: (Output File Strategy "members") ( ## Enumeration Members -| Enumeration Member | Value | Description | -| ------ | ------ | ------ | -| \`member1\` | \`"member1"\` | The subroutine recursively parsed the hexadecimal data. | +| Enumeration Member | Value | Description | Defined in | +| ------ | ------ | ------ | ------ | +| \`member1\` | \`"member1"\` | The subroutine recursively parsed the hexadecimal data. | [index.ts:1](http://source-url) | " `; @@ -174,6 +174,10 @@ Adds two numbers together. ## Returns \`number\` + +## Source + +[index.ts:1](http://source-url) " `; @@ -200,13 +204,13 @@ exports[`Comments should get tables for properties: (Output File Strategy "membe ## Properties -| Property | Modifier | Type | Default Value | Description | Overrides | Inherited from | -| ------ | ------ | ------ | ------ | ------ | ------ | ------ | -| \`prop1\` | \`private\` | \`boolean\` | \`undefined\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | - | - | -| \`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. | - | - | -| \`prop3?\` | \`public\` | \`string\` | \`undefined\` | > Example of Triple Code Block \`def greet(name): print("Hello, " + name + "!")\` | - | - | -| ~~\`propA\`~~ | \`public\` | \`string\` | \`'propAValue'\` | **Deprecated** | [\`BaseClassProperties\`](BaseClassProperties.md).\`propA\` | - | -| \`propB\` | \`public\` | \`string\` | \`undefined\` | - | - | [\`BaseClassProperties\`](BaseClassProperties.md).\`propB\` | +| Property | Modifier | Type | Default Value | Description | Overrides | Inherited from | Defined in | +| ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | +| \`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) | " `; @@ -368,11 +372,15 @@ exports[`Comments should get tables for type declarations: (Output File Strategy ## Type declaration -| Member | Type | Description | -| ------ | ------ | ------ | -| \`declaration1\` | \`boolean\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | -| \`declaration2\` | \`boolean\` | The subroutine recursively parsed the hexadecimal data. to generate the binary output for input validation. | -| \`declaration3\` | \`"declaration3"\` | - | +| Member | Type | Description | Defined in | +| ------ | ------ | ------ | ------ | +| \`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) | + +## Source + +[index.ts:1](http://source-url) " `; @@ -439,6 +447,10 @@ to generate the binary output for input validation. + +## Source + +[index.ts:1](http://source-url) " `; @@ -469,6 +481,10 @@ text outside of the code block as regular text. \`\`\`ts factorial(1) \`\`\` + +## Source + +[index.ts:1](http://source-url) " `; @@ -499,5 +515,9 @@ text outside of the code block as regular text. \`\`\`ts factorial(1) \`\`\` + +## Source + +[index.ts:1](http://source-url) " `;