diff --git a/README.md b/README.md index 0ec382820..858aa1aab 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ This project is a collection of packages designed for generate TypeScript API documentation as Markdown. +## Documentation + +Please see [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org). + ## Packages | Package | Version | Downloads | Changelog @@ -14,10 +18,6 @@ This project is a collection of packages designed for generate TypeScript API do [typedoc-vitepress-theme](./packages/typedoc-vitepress-theme#readme) | [![npm](https://img.shields.io/npm/v/typedoc-vitepress-theme.svg?logo=npm)](https://www.npmjs.com/package/typedoc-vitepress-theme) | ![Downloads](https://img.shields.io/npm/dw/typedoc-vitepress-theme?label=↓) | [Changelog](./packages/typedoc-vitepress-theme/CHANGELOG.md) | [docusaurus-plugin-typedoc](./packages/docusaurus-plugin-typedoc#readme) | [![npm](https://img.shields.io/npm/v/docusaurus-plugin-typedoc.svg?logo=npm)](https://www.npmjs.com/package/docusaurus-plugin-typedoc) | ![Downloads](https://img.shields.io/npm/dw/docusaurus-plugin-typedoc?label=↓) | [Changelog](./packages/docusaurus-plugin-typedoc/CHANGELOG.md) | -## Documentation - -Please see [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org). - ## Contributing If you would like to contribute towards this project please read the [contributing guide](./CONTRIBUTING.md). diff --git a/devtools/scripts/generate-readmes.ts b/devtools/scripts/generate-readmes.ts index ae9e80719..b8efb70fe 100755 --- a/devtools/scripts/generate-readmes.ts +++ b/devtools/scripts/generate-readmes.ts @@ -38,6 +38,12 @@ function writeRepositoryReadme(packages: any) { 'This project is a collection of packages designed for generate TypeScript API documentation as Markdown.', ); + readme.push('## Documentation'); + + readme.push( + 'Please see [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org).', + ); + readme.push('## Packages'); const headers: string[] = []; headers.push('| Package | Version | Downloads | Changelog '); @@ -60,12 +66,6 @@ function writeRepositoryReadme(packages: any) { readme.push(table.join('\n')); - readme.push('## Documentation'); - - readme.push( - 'Please see [typedoc-plugin-markdown.org](https://typedoc-plugin-markdown.org).', - ); - readme.push('## Contributing'); readme.push( diff --git a/docs/pages/docs/options/file-options.mdx b/docs/pages/docs/options/file-options.mdx index cf06ecd15..bf9973e65 100644 --- a/docs/pages/docs/options/file-options.mdx +++ b/docs/pages/docs/options/file-options.mdx @@ -80,6 +80,37 @@ Ignored when `--outputFileStrategy` is equal to `"modules"` 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: + +``` + ├── README.md + ├── module-a/ + │ ├── classes/ + │ │ ├── ClassA.md + │ │ └── ClassB.md + │ └── functions/ + │ │ ├── FunctionA.md + │ │ └── FunctionB.md + └── module-b/ + └── classes/ + ├── ClassA.md + └── ClassB.md +``` + +Flattened output: + +``` + ├── README.md + ├── module-a.Class.ClassA.md + ├── module-a.Class.ClassB.md + ├── module-a.Function.functionA.md + ├── module-a.Function.functionB.md + ├── module-b.Class.ClassA.md + └── module-b.Class.ClassB.md +``` + ```json filename="typedoc.json" { "flattenOutputFiles": false @@ -157,6 +188,21 @@ This option will remove reference to `@scope` in the path when generating files The following will be the directory structure for packages named `@scope/package-1` and `@scope/package-2`: +Output when set to `false` (default): + +``` + └──@scope/ + ├── package-1/ + └── package-2/ +``` + +Output when set to `true`: + +``` + ├── package-1/ + └── package-2/ +``` + Ignored if `flattenOutputFiles` is set to `true`. ```json filename="typedoc.json" diff --git a/docs/pages/plugins/docusaurus.mdx b/docs/pages/plugins/docusaurus.mdx index 008d2fcc9..e8c78f71e 100644 --- a/docs/pages/plugins/docusaurus.mdx +++ b/docs/pages/plugins/docusaurus.mdx @@ -47,7 +47,7 @@ The following is a simple example of a Docusaurus project running TypeDoc. title="View Code on GitHub" icon={} arrow={true} - href="https://github.com/typedoc2md/typedoc-plugin-markdown-examples/tree/main/examples/integrations/docusaurus" + href="https://github.com/typedoc2md/typedoc-plugin-markdown-examples/tree/main/integrations/docusaurus" target="_blank" /> diff --git a/docs/pages/plugins/github-wiki.mdx b/docs/pages/plugins/github-wiki.mdx index cecc97a4f..814c98e14 100644 --- a/docs/pages/plugins/github-wiki.mdx +++ b/docs/pages/plugins/github-wiki.mdx @@ -33,7 +33,7 @@ The following is a simple example of a GithubWiki project running TypeDoc. title="View Source on Github" icon={} arrow={true} - href="https://github.com/typedoc2md/typedoc-plugin-markdown-examples/tree/main/examples/integrations/github-wiki" + href="https://github.com/typedoc2md/typedoc-plugin-markdown-examples/tree/main/integrations/github-wiki" target="_blank" /> diff --git a/docs/pages/plugins/vitepress.mdx b/docs/pages/plugins/vitepress.mdx index b51ec6a86..e5b1f1299 100644 --- a/docs/pages/plugins/vitepress.mdx +++ b/docs/pages/plugins/vitepress.mdx @@ -41,7 +41,7 @@ The following is a simple example of a VitePress project running TypeDoc. title="View Code on GitHub" icon={} arrow={true} - href="https://github.com/typedoc2md/typedoc-plugin-markdown-examples/tree/main/examples/integrations/vitepress" + href="https://github.com/typedoc2md/typedoc-plugin-markdown-examples/tree/main/integrations/vitepress" target="_blank" /> diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts index 780b5db51..e1ee2b143 100644 --- a/packages/typedoc-plugin-markdown/src/options/declarations.ts +++ b/packages/typedoc-plugin-markdown/src/options/declarations.ts @@ -100,6 +100,37 @@ export const membersWithOwnFile: Partial = { /** * 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: + * + * ``` + * ├── README.md + * ├── module-a/ + * │ ├── classes/ + * │ │ ├── ClassA.md + * │ │ └── ClassB.md + * │ └── functions/ + * │ │ ├── FunctionA.md + * │ │ └── FunctionB.md + * └── module-b/ + * └── classes/ + * ├── ClassA.md + * └── ClassB.md + * ``` + * + * Flattened output: + * + * ``` + * ├── README.md + * ├── module-a.Class.ClassA.md + * ├── module-a.Class.ClassB.md + * ├── module-a.Function.functionA.md + * ├── module-a.Function.functionB.md + * ├── module-b.Class.ClassA.md + * └── module-b.Class.ClassB.md + * ``` + * * @category File */ export const flattenOutputFiles: Partial = { @@ -174,6 +205,21 @@ export const entryModule: Partial = { * * The following will be the directory structure for packages named `@scope/package-1` and `@scope/package-2`: * + * Output when set to `false` (default): + * + * ``` + * └──@scope/ + * ├── package-1/ + * └── package-2/ + * ``` + * + * Output when set to `true`: + * + * ``` + * ├── package-1/ + * └── package-2/ + * ``` + * * Ignored if `flattenOutputFiles` is set to `true`. * * @category File