chore: Refactored and updated code comments

.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-theme.md

@@ -0,0 +1,42 @@
+# Custom Theme
+
+If required the theme can be further extended using recommended patterns of the HTML theme - please see TypeDoc's [custom theme](https://github.com/TypeStrong/typedoc/blob/master/internal-docs/custom-themes.md) docs.
+
+This approach can be implemented in this example showing how the header and footer templates can be customized with a new theme using a customn plugin.
+
+```ts filename="custom-plugin.ts"
+import { Application, PageEvent, Reflection } from "typedoc";
+import {
+  MarkdownTheme,
+  MarkdownThemeRenderContext,
+} from "typedoc-plugin-markdown";
+
+export function load(app: Application) {
+  app.renderer.defineTheme("custom-markdown-theme", CustomTheme);
+}
+
+class CustomMarkdownTheme extends MarkdownTheme {
+  override getRenderContext(pageEvent: PageEvent<Reflection>) {
+    return new CustomMarkdownTheme(pageEvent, this.application.options);
+  }
+}
+
+class CustomMarkdownTheme extends MarkdownThemeRenderContext {
+  override header = () => {
+    return "CUSTOM HEADER HERE";
+  };
+
+  override footer = () => {
+    return "CUSTOM FOOTER HERE";
+  };
+}
+```
+
+To theme can then be added to the TypeDoc config as follows:
+
+```json filename="typedoc.json"
+{
+  "plugin": ["typedoc-plugin-markdown", "./dist/custom-plugin"],
+  "theme": "custom-markdown-theme"
+}
+```

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

@@ -0,0 +1,3 @@
+{
+  "api": "API"
+}

docs/pages/guides/custom-theme/api.md

@@ -0,0 +1,3 @@
+# API
+
+Please note you have a theme context.