fix(core): fix index generation issues

Author: tgreyuk

.changeset/neat-monkeys-provide.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': minor
+---
+
+- Remove extraneous "Index" headings.

.changeset/tender-snails-dress.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Expose global documents with "packages" entryPointStrategy.

.gitignore

@@ -9,7 +9,7 @@ samples
 typedoc-examples
 out
 html
-/devdocs-html
+/devguide-html
 
 # dependencies
 node_modules

packages/README.md renamed to GETTING_STARTED.md

@@ -1,17 +1,11 @@
-# Developer Guide
+---
+title: Getting Started
+description: How to start developing locally.
+---
 
-## Monorepo Overview
+# Getting Started
 
-This is a simple monorepo managed by [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces).
-
-Please view individual packages for further insights:
-
-- {@link typedoc-plugin-markdown} is the core package and is the package that is used to generate the markdown documentation.
-- {@link typedoc-plugin-frontmatter} and {@link typedoc-plugin-remark} provide metadata or adjust the output.
-- {@link typedoc-github-wiki-theme}, {@link typedoc-gitlab-wiki-theme},
-  {@link typedoc-vitepress-theme} and {@link docusaurus-plugin-typedoc} target specific implementations.
-
-## Machine Setup
+## 1. Machine Setup
 
 **1. Fork and clone the repository**
 
@@ -47,4 +41,16 @@ Test all packages in the workspace:
 npm run test
 ```
 
+## 2. Contributing to packages
+
 If the project builds and the tests run successfully you are ready to start contributing to the project.
+
+This is a simple monorepo managed by [npm workspaces](https://docs.npmjs.com/cli/v7/using-npm/workspaces).
+
+{@link typedoc-plugin-markdown} is the core package and is the package that is used to generate the Markdown documentation.
+
+Child packages all depend on the core package and provide further functionality:
+
+- {@link typedoc-plugin-frontmatter} and {@link typedoc-plugin-remark} provide metadata or adjust the output.
+- {@link typedoc-github-wiki-theme}, {@link typedoc-gitlab-wiki-theme},
+  {@link typedoc-vitepress-theme} and {@link docusaurus-plugin-typedoc} target specific implementations.

devtools/packages/prebuild-options/tasks/generate-models.ts

@@ -72,6 +72,7 @@ import { ManuallyValidatedOption } from 'typedoc'`);
         theme_member_plural: [];
         theme_modifier: [];
         theme_name: [];
+        theme_package: [];
         theme_packages: [];
         theme_type: [];
         theme_value: [];

devtools/typedoc-plugins/typedoc-default-values.mjs

@@ -44,7 +44,7 @@ export function load(app) {
   );
 }
 function getTag(value) {
-  return new CommentTag('@defaultValue', [
+  return new CommentTag('@initializer', [
     {
       kind: 'code',
       text: makeCodeBlock(value),

devtools/typedoc-plugins/typedoc-replace-filetree.mjs

@@ -0,0 +1,24 @@
+import { Converter } from 'typedoc';
+
+export function load(app) {
+  app.converter.on(
+    Converter.EVENT_CREATE_DECLARATION,
+    (_context, reflection) => {
+      if (
+        reflection.comment &&
+        reflection?.comment?.summary &&
+        reflection?.comment?.summary.length
+      ) {
+        reflection.comment.summary = reflection.comment.summary.map(
+          (summary) => ({
+            ...summary,
+            text: summary.text.replace(
+              /<FileTree\b[^>]*>.*?<\/FileTree>/gs,
+              '*See public docs for file tree example.*',
+            ),
+          }),
+        );
+      }
+    },
+  );
+}

devtools/typedoc-plugins/typedoc-symbols.mjs

@@ -31,6 +31,7 @@ export function load(app) {
       const interfaces = ['TypeDocOptions', 'TypeOperatorType'];
       const classes = [
         'Application',
+        'Context',
         'DefaultThemeRenderContext',
         'Event',
         'EventHooks',

docs/pages/docs/options/file-options.mdx

@@ -16,7 +16,7 @@ TypeDoc generates documentation models according to exports derived from the giv
 This option provides some flexibility as to how files are generated by organising how these exports are organized on individual pages.
 Note that each module and namespace will at a minimum have its own page.
 
-The available keys are `"members"` (default), `"categories"`, and `"modules"`.
+The available keys are `"members"` (default) and `"modules"`.
 
 **"members"**
 

docs/pages/docs/versioning.mdx

@@ -8,6 +8,13 @@ Please note that TypeDoc is still released within the 0.x.x range and may includ
 
 A new minor version of the plugin and be released with each minor TypeDoc version, and we will attempt to release in a non-breaking manner.
 
+Besides the TypeDoc release versions, we aim to follow semantic versioning for the plugin:
+
+- Bug fixes including minor UI tweaks will be released as patch versions.
+- New features/options will be released as minor versions.
+- UI changes implemented in a non-breaking manner will be released as minor versions.
+- Breaking changes including option changes and fundamental UI changes will be released as major versions.
+
 ## Compatibility Table
 
 We will follow the Node.js and TypeScript versions as specified in the TypeDoc `package.json` file.

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
 
 <Callout emoji="💡">Configures the autogenerated Docusaurus sidebar.</Callout>
 

docs/pages/plugins/frontmatter/options.mdx

@@ -2,7 +2,7 @@ import { Callout } from "nextra/components";
 
 # Options
 
-## --frontmatterGlobals
+## frontmatterGlobals
 
 <Callout emoji="💡">
   Specify static variables to be added to all frontmatter blocks.
@@ -26,7 +26,7 @@ sidebar: true
 }
 ```
 
-## --readmeFrontmatter
+## readmeFrontmatter
 
 <Callout emoji="💡">
   Specify static variables to be added to the readme page only.
@@ -42,7 +42,7 @@ sidebar: true
 }
 ```
 
-## --indexFrontmatter
+## indexFrontmatter
 
 <Callout emoji="💡">
   Specify static variables to be added to the index page only.
@@ -58,7 +58,7 @@ sidebar: true
 }
 ```
 
-## --frontmatterCommentTags
+## frontmatterCommentTags
 
 <Callout emoji="💡">
   Specify which comment block tags should be added to frontmatter.
@@ -70,12 +70,12 @@ Frontmatter variables can be added by extracting comments from block (@) tags.
 
 Please note tags must be added to the comment blocks of the symbol exported to a page.
 
-```ansi filename="Block Tags (someModule.ts)"
+```ts filename="Block Tags (someModule.ts)"
 /**
-* @author Joe Bloggs
-*
-* @description A description that will be added to frontmatter.
-*/
+ * @author Joe Bloggs
+ *
+ * @description A description that will be added to frontmatter.
+ */
 ```
 
 ```yaml filename="YAML (someModule.md)"
@@ -91,7 +91,7 @@ description: A description that will be added to frontmatter.
 }
 ```
 
-## --preserveFrontmatterCommentTags
+## preserveFrontmatterCommentTags
 
 <Callout emoji="💡">
   Preserve tags defined in frontmatter block tags in output.
@@ -105,7 +105,7 @@ description: A description that will be added to frontmatter.
 }
 ```
 
-## --frontmatterNamingConvention
+## frontmatterNamingConvention
 
 <Callout emoji="💡">
   The naming convention that variables should be output as.{" "}

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
 
 <Callout emoji="💡">Configures the autogenerated `_sidebar.md file`.</Callout>
 

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
 
 <Callout emoji="💡">Configures the autogenerated `_Sidebar.md file`.</Callout>
 

docs/pages/plugins/remark/options.mdx

@@ -2,7 +2,7 @@ import { Callout } from "nextra/components";
 
 # Options
 
-## --remarkPlugins
+## remarkPlugins
 
 <Callout emoji="💡">An array of remark plugin names to be executed.</Callout>
 
@@ -28,7 +28,7 @@ Options can be provided as either an array of strings or an array of strings wit
 }
 ```
 
-## --defaultRemarkPlugins
+## defaultRemarkPlugins
 
 <Callout emoji="💡">
   A set of flags that control the enabling or disabling of remark plugins that
@@ -53,7 +53,7 @@ If you'd like to disable any of these default plugins, simply set the correspond
 }
 ```
 
-## --remarkStringifyOptions
+## remarkStringifyOptions
 
 <Callout emoji="💡">Custom options for the remark-stringify plugin.</Callout>
 

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
 
 <Callout emoji="💡">The path to the VitePress project root.</Callout>
 
@@ -57,7 +57,7 @@ Requires the following config:
 }
 ```
 
-## --sidebar
+## sidebar
 
 <Callout emoji="💡">Configures the autogenerated VitePress sidebar.</Callout>
 

package.json

@@ -11,8 +11,7 @@
     "devtools/packages/*"
   ],
   "scripts": {
-    "docs": "ts-node ./devtools/scripts/generate-readmes && node ./devtools/scripts/tocs.mjs",
-    "devdocs": "npm run build --workspace typedoc-plugin-markdown && typedoc",
+    "docs": "tsx ./devtools/scripts/generate-readmes && node ./devtools/scripts/tocs.mjs && npm run build --workspace typedoc-plugin-markdown && typedoc",
     "build-all": "npm run build --workspaces --if-present",
     "test-all": "npm run test --workspaces --if-present",
     "test-and-update-all": "npm run test:update --workspaces --if-present",

packages/typedoc-plugin-frontmatter/src/options/declarations.ts

@@ -62,7 +62,7 @@ export const indexFrontmatter: Partial<DeclarationOption> = {
  *
  * Please note tags must be added to the comment blocks of the symbol exported to a page.
  *
- *  ```ansi filename="Block Tags (someModule.ts)"
+ *  ```ts filename="Block Tags (someModule.ts)"
  *  \/**
  *  * \@author Joe Bloggs
  *  *

packages/typedoc-plugin-markdown/src/_typedoc.d.ts

@@ -91,6 +91,7 @@ declare module 'typedoc' {
       theme_member_plural: [];
       theme_modifier: [];
       theme_name: [];
+      theme_package: [];
       theme_packages: [];
       theme_type: [];
       theme_value: [];

packages/typedoc-plugin-markdown/src/index.ts

@@ -1,7 +1,7 @@
 /**
- * The plugin entrypoint and bootstrapping of the plugin.
+ * The entry point for initializing and bootstrapping the plugin.
  *
- * @module
+ * @module core
  */
 import { getTranslatable } from '@plugin/internationalization/translatable.js';
 import { declarations } from '@plugin/options/index.js';
@@ -17,17 +17,30 @@ import {
   ParameterType,
 } from 'typedoc';
 import { render } from './renderer/render.js';
+
 /**
  * The function that is called by TypeDoc to bootstrap the plugin.
  *
- * Here we expose additional TypeDoc options and make some adjustments.
+ * @remarks
+ *
+ * The load function exposes additional TypeDoc options and make some adjustments.
  *
  * This method is not intended to be consumed in any other context that via the `plugin` option.
+ *
+ * The load functions:
+ *
+ * 1. Bootstrap the plugin options
+ * 2. Configures markdown outputs
+ * 3. Configures localization
+ * 4. Applies any other behaviour
+ *
+ * The module also exports anything that is available publicly.
+ *
  */
 export function load(app: Application) {
   /**
    * ====================
-   * 1. Bootstrap Options
+   * 1. Bootstrap options
    * ====================
    */
 

packages/typedoc-plugin-markdown/src/internationalization/locales/en.ts

@@ -18,6 +18,7 @@ export const translatable: TranslatableStrings = {
   theme_member_plural: 'Members',
   theme_modifier: 'Modifier',
   theme_name: 'Name',
+  theme_package: 'Package',
   theme_packages: 'Packages',
   theme_type: 'Type',
   theme_value: 'Value',

packages/typedoc-plugin-markdown/src/internationalization/locales/jp.ts

@@ -19,6 +19,7 @@ export const translatable: Partial<TranslatableStrings> = {
   theme_member_plural: 'メンバー',
   theme_modifier: '修飾子',
   theme_name: '名前',
+  theme_package: 'パッケージ',
   theme_packages: 'パッケージ',
   theme_type: 'タイプ',
   theme_value: '値',

packages/typedoc-plugin-markdown/src/internationalization/locales/ko.ts

@@ -18,6 +18,7 @@ export const translatable: Partial<TranslatableStrings> = {
   theme_member_plural: '멤버들',
   theme_modifier: '수정자',
   theme_name: '이름',
+  theme_package: '패키지',
   theme_packages: '패키지',
   theme_type: '유형',
   theme_value: '값',

packages/typedoc-plugin-markdown/src/internationalization/locales/zh.ts

@@ -18,6 +18,7 @@ export const translatable: Partial<TranslatableStrings> = {
   theme_member_plural: '成员',
   theme_modifier: '修饰符',
   theme_name: '名称',
+  theme_package: '包',
   theme_packages: '包',
   theme_type: '类型',
   theme_value: '值',

packages/typedoc-plugin-markdown/src/internationalization/translatable.ts

@@ -11,7 +11,7 @@ import { Application } from 'typedoc';
  *
  * These will then be merged with the main set of TypeDoc string.
  *
- * @category Methods
+ * @category Functions
  */
 export function getTranslatable(app: Application) {
   const LOCALES = {

packages/typedoc-plugin-markdown/src/libs/markdown/index.ts

@@ -1,3 +1,9 @@
+/**
+ * Helpers for generating markdown.
+ *
+ * @module
+ */
+
 export * from './back-ticks.js';
 export * from './block-quote-block.js';
 export * from './bold.js';