chore(docs): updated docs

typedoc2md · Jun 24, 2024 · be3c5e3 · be3c5e3
1 parent 2264f02
commit be3c5e3
Show file tree

Hide file tree

Showing 7 changed files with 105 additions and 13 deletions.
diff --git 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
@@ -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
@@ -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
@@ -47,7 +47,7 @@ The following is a simple example of a Docusaurus project running TypeDoc.
     title="View Code on GitHub"
     icon={<FontAwesomeIcon icon={faGithub} />}
     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"
   />
 </Cards>
diff --git 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={<FontAwesomeIcon icon={faGithub} />}
     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"
   />
 </Cards>
diff --git 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={<FontAwesomeIcon icon={faGithub} />}
     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"
   />
 </Cards>
diff --git 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<DeclarationOption> = {
 /**
  * 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<DeclarationOption> = {
@@ -174,6 +205,21 @@ export const entryModule: Partial<DeclarationOption> = {
  *
  * 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