chore: Refactoring and code fixes

.changeset/dirty-walls-serve.md

@@ -0,0 +1,6 @@
+---
+"typedoc-plugin-markdown": patch
+---
+
+- Expose theme hooks similar to default theme.
+- Expose TypedDoc media and include syntax.

.changeset/happy-rats-help.md

@@ -0,0 +1,8 @@
+---
+"docusaurus-plugin-typedoc": patch
+"typedoc-github-wiki-theme": patch
+"typedoc-gitlab-wiki-theme": patch
+"typedoc-vitepress-theme": patch
+---
+
+- Update core package dependency

dev-packages/helpers/src/constants.ts

@@ -1,47 +1,52 @@
 import { DocsConfig } from './models';
 
-export const DECLARATIONS_PATH = `${process.cwd()}/src/options/declarations.ts`;
-
 export const PRESETS_PATH = `${process.cwd()}/src/options/presets.ts`;
 
 export const DOCS_CONFIG: Record<string, DocsConfig> = {
   ['typedoc-plugin-markdown']: {
+    declarationsPath: `${process.cwd()}/src/plugin/options/declarations.ts`,
     optionsPath: 'options',
     docsPath: '',
     declarations: true,
     presets: false,
   },
   ['typedoc-plugin-frontmatter']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'utilities/frontmatter',
     docsPath: '/utilities/frontmatter',
     declarations: true,
     presets: false,
   },
   ['typedoc-plugin-remark']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'utilities/remark',
     docsPath: '/utilities/remark',
     declarations: true,
     presets: false,
   },
   ['typedoc-github-wiki-theme']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'themes/github-wiki',
     docsPath: '/themes/github-wiki',
     declarations: true,
     presets: true,
   },
   ['typedoc-gitlab-wiki-theme']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'themes/gitlab-wiki',
     docsPath: '/themes/gitlab-wiki',
     declarations: true,
     presets: true,
   },
   ['typedoc-vitepress-theme']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: 'themes/vitepress',
     docsPath: '/themes/vitepress',
     declarations: true,
     presets: false,
   },
   ['docusaurus-plugin-typedoc']: {
+    declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     optionsPath: '/integrations/docusaurus/options',
     docsPath: '/integrations/docusaurus',
     declarations: false,

dev-packages/helpers/src/models.ts

@@ -1,4 +1,5 @@
 export interface DocsConfig {
+  declarationsPath: string;
   optionsPath: string;
   docsPath: string;
   declarations: boolean;

dev-packages/prebuild-options/cli.ts

@@ -10,7 +10,7 @@ main();
 async function main() {
   const docsConfig: DocsConfig = DOCS_CONFIG[getPackageName()];
   if (docsConfig.declarations) {
-    await generateModels();
+    await generateModels(docsConfig.declarationsPath);
   }
   await generateDocs(docsConfig);
   consola.success(`[${getPackageName()}] Prebuild options complete`);

dev-packages/prebuild-options/tasks/generate-docs.ts

@@ -1,4 +1,3 @@
-import { DECLARATIONS_PATH } from '@dev-packages/helpers';
 import { DocsConfig } from '@dev-packages/helpers/src/models';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -21,8 +20,8 @@ export async function generateDocs(docsConfig: DocsConfig) {
 
   // DECLARATIONS
   if (docsConfig.declarations) {
-    const declarationsConfig: any = await import(DECLARATIONS_PATH);
-    const configFileTs = project.getSourceFile(DECLARATIONS_PATH);
+    const declarationsConfig: any = await import(docsConfig.declarationsPath);
+    const configFileTs = project.getSourceFile(docsConfig.declarationsPath);
 
     const optionsVariableStatements =
       configFileTs?.getVariableStatements() as VariableStatement[];

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

@@ -1,4 +1,3 @@
-import { DECLARATIONS_PATH } from '@dev-packages/helpers';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as prettier from 'prettier';
@@ -8,8 +7,8 @@ import { DeclarationOption, ParameterType } from 'typedoc';
  * Creates models for plugin options
  */
 
-export async function generateModels() {
-  const optionsConfig = await import(DECLARATIONS_PATH);
+export async function generateModels(declarationsPath: string) {
+  const optionsConfig = await import(declarationsPath);
 
   const mixedTypes = (Object.entries(optionsConfig) as any).filter(
     ([name, option]) =>
@@ -59,10 +58,8 @@ export async function generateModels() {
   `;
 
   const optionsModelFile = path.join(
-    process.cwd(),
-    'src',
-    'options',
-    'models.ts',
+    path.dirname(declarationsPath),
+    'option-types.ts',
   );
 
   const formatted = await prettier.format(optionsOutput, {

docs/pages/_meta.json

@@ -2,6 +2,7 @@
   "index": "Introduction",
   "quick-start": "",
   "options": "",
+  "guides": "Guides",
   "examples": "",
   "-- RelatedPlugin": {
     "type": "separator",

docs/pages/guides/custom-output.mdx

@@ -0,0 +1,99 @@
+import { Callout, FileTree } from 'nextra/components';
+
+# Custom Output
+
+Output can be further extended following the an adapted version of TypeDoc's [Custom Theme docs](https://github.com/TypeStrong/typedoc/blob/master/internal-docs/custom-themes.md).
+
+## Local plugins
+
+To get started a create a local TypeDoc plugin file. TypeDoc supports both ESM and CommonJS
+modules. This example is a guide only and written as ESM using an `.mjs` file extension - please adapt to your own needs.
+
+```js filename="custom-plugin.mjs"
+// @ts-check
+
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ */
+export function load(app) {
+  // Theme customization should be placed in the load function.
+}
+```
+
+The file can the be referenced in the `typedoc.json` file.
+
+```json filename="typedoc.json"
+{
+  "plugin": ["typedoc-plugin-markdown", "./custom-plugin.mjs"]
+}
+```
+
+## Hooks
+
+Hooks allows Markdown (or HTML) to be injected into the output in specific locations and are the most basic form form of customization.
+
+```js filename="local-plugins/custom-plugin.mjs"
+// @ts-check
+
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ */
+export function load(app) {
+  // Add a hook to insert markdown at the top of the page.
+  app.renderer.markdownHooks.on(
+    'page.begin',
+    () => '> This is some markdown at the top of the page',
+  );
+}
+```
+
+Available hooks are:
+
+- `page.begin` - Applied at the start of the markdown output.
+- `page.end` - Applied at the end of the markdown output.
+- `content.begin` - Applied before the main markdown content is rendered..
+
+## Custom Theme Class
+
+If there are some specific customization not achievable with hooks then a more advanced customization can be achieved by providing a new theme class which returns a different context class.
+
+In theory all available templates, partials and hepers can be overriden (and added to) with custom implementations, but please proceed with caution.
+
+Please consider raising a PR to the plugin directly if you think your customizations would be useful to others.
+
+```js filename="custom-plugin.mjs"
+// @ts-check
+
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ */
+export function load(app) {
+  // Add a hook to insert markdown at the top of the page.
+  app.renderer.defineTheme('custom-theme', MyMarkdownTheme);
+}
+
+class MyMarkdownTheme extends MarkdownTheme {
+  /**
+   * @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page
+   */
+  getRenderContext(page) {
+    return new MyMarkdownThemeRenderContext(
+      this,
+      page,
+      this.application.options,
+    );
+  }
+}
+
+class MyMarkdownThemeRenderContext extends MarkdownThemeRenderContext {
+  partials = {
+    ...this.partials,
+    /**
+     * @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page
+     */
+    header: (page) => {
+      return `Welcome to ${page.project.name} custom header!`;
+    },
+  };
+}
+```

docs/pages/guides/custom-output/_meta.json

@@ -0,0 +1 @@
+{}

docs/pages/quick-start.mdx

@@ -31,7 +31,6 @@ The majority of [TypeDoc's options](https://typedoc.org/options/) are supported,
 
 Some typical (and frequently asked about) TypeDoc options that might be useful are:
 
-- Using [githubPages](https://typedoc.org/options/output/#githubpages) to remove the generated `.nojekyll` file.
 - Using [hideGenerator](https://typedoc.org/options/output/#hidegenerator) to prevent outputting links in the footer.
 - Using [disableSources](https://typedoc.org/options/output/#disablesources) to prevent outputting source references.
 - Setting [readme](https://typedoc.org/options/input/#readme) to `none` to exclude the project readme from the docs.

examples/docusaurus3/docusaurus.config.js

@@ -52,6 +52,7 @@ const config = {
         readme: 'none',
         sidebar: { pretty: true },
         outputFileStrategy: 'members',
+        cleanOutputDir: true,
       },
     ],
     [
@@ -61,6 +62,7 @@ const config = {
         out: './docs/api-2',
         ...require(path.join(__dirname, '../../stubs/typedoc.cjs')),
         entryPoints: '../../stubs/src/groups/**/*.ts',
+        cleanOutputDir: true,
       },
     ],
     [
@@ -73,6 +75,7 @@ const config = {
         readme: 'none',
         outputFileStrategy: 'modules',
         entryModule: 'index',
+        cleanOutputDir: true,
       },
     ],
     [

packages/docusaurus-plugin-typedoc/package.json

@@ -23,7 +23,8 @@
     "prepublishOnly": "npm run lint && npm run build",
     "build": "rm -rf ./dist && tsc",
     "build-and-test": "npm run build && npm run test",
-    "test": "jest"
+    "test": "jest",
+    "test:update": "npm test -- -u"
   },
   "author": "Thomas Grey",
   "license": "MIT",

packages/docusaurus-plugin-typedoc/src/options.ts

@@ -7,7 +7,6 @@ const DEFAULT_PLUGIN_OPTIONS = {
   hidePageHeader: true,
   entryFileName: 'index.md',
   theme: 'docusaurus',
-  githubPages: false,
   sidebar: {
     autoConfiguration: true,
     pretty: false,

packages/docusaurus-plugin-typedoc/src/plugin.ts

@@ -56,10 +56,6 @@ async function generateTypedoc(context: any, opts: Partial<PluginOptions>) {
 
   const outputDir = app.options.getValue('out');
 
-  if (options.cleanOutputDir) {
-    removeDir(outputDir);
-  }
-
   if (context.siteConfig?.markdown?.format !== 'mdx') {
     app.renderer.on(PageEvent.END, (event: PageEvent) => {
       event.contents = event.contents?.replace(/\\</g, '<');
@@ -121,30 +117,3 @@ module.exports = typedocSidebar.items;`,
     await app.generateDocs(project, outputDir);
   }
 }
-
-export function writeFileSync(fileName: string, data: string) {
-  fs.mkdirSync(path.dirname(normalizePath(fileName)), { recursive: true });
-  fs.writeFileSync(normalizePath(fileName), data);
-}
-
-export function normalizePath(path: string) {
-  return path.replace(/\\/g, '/');
-}
-
-export function removeDir(path: string) {
-  if (fs.existsSync(path)) {
-    const files = fs.readdirSync(path);
-    if (files.length > 0) {
-      files.forEach(function (filename) {
-        if (fs.statSync(path + '/' + filename).isDirectory()) {
-          removeDir(path + '/' + filename);
-        } else {
-          fs.unlinkSync(path + '/' + filename);
-        }
-      });
-      fs.rmdirSync(path);
-    } else {
-      fs.rmdirSync(path);
-    }
-  }
-}

packages/docusaurus-plugin-typedoc/src/theme.ts

@@ -17,13 +17,16 @@ export class DocusuaurusTheme extends MarkdownTheme {
 
 class DocusuaurusThemeThemeRenderContext extends MarkdownThemeRenderContext {
   // adds space around type arguments as docusaurus generates broken links without it in certain use-cases (see https://github.com/facebook/docusaurus/issues/9518)
-  override typeArguments = (typeArguments: SomeType[]) => {
-    return `\\< ${typeArguments
-      .map((typeArgument) =>
-        typeArgument instanceof ReflectionType
-          ? this.reflectionType(typeArgument)
-          : this.someType(typeArgument),
-      )
-      .join(', ')} \\>`;
+  override partials = {
+    ...this.partials,
+    typeArguments: (typeArguments: SomeType[]) => {
+      return `\\< ${typeArguments
+        .map((typeArgument) =>
+          typeArgument instanceof ReflectionType
+            ? this.partials.reflectionType(typeArgument)
+            : this.partials.someType(typeArgument),
+        )
+        .join(', ')} \\>`;
+    },
   };
 }

packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap

@@ -14,10 +14,6 @@ exports[`Docusaurus: Defaults should render 1`] = `
 
 - [module-1](module-1/index.md)
 - [module-2](module-2/index.md)
-
-***
-
-Generated using [TypeDoc](https://typedoc.org) and [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org).
 "
 `;
 
@@ -35,9 +31,5 @@ exports[`Docusaurus: Global members should render 2 1`] = `
 
 - [module-1](module-1/index.md)
 - [module-2](module-2/index.md)
-
-***
-
-Generated using [TypeDoc](https://typedoc.org) and [typedoc-plugin-markdown](https://typedoc-plugin-markdown.org).
 "
 `;

packages/docusaurus-plugin-typedoc/test/specs/docusaurus.spec.ts

@@ -13,6 +13,8 @@ async function bootstrap(
     entryPoints,
     tsconfig: ['./test/stubs/tsconfig.json'],
     readme: 'none',
+    logLevel: 'Warn',
+    hideGenerator: true,
   };
 
   const plugin = typedocPlugin(

packages/typedoc-github-wiki-theme/package.json

@@ -22,7 +22,8 @@
     "build": "tsc",
     "build-and-test": "npm run build && npm run test",
     "pretest": "ts-node ./test/__scripts__/prepare.ts",
-    "test": "jest"
+    "test": "jest",
+    "test:update": "npm run build && npm test -- -u"
   },
   "author": "Thomas Grey",
   "license": "MIT",