chore: restructured dev directory

.changeset/config.json

@@ -10,9 +10,5 @@
   "access": "public",
   "baseBranch": "next",
   "updateInternalDependencies": "minor",
-  "ignore": [
-    "@dev-packages/helpers",
-    "@dev-packages/prebuild-options",
-    "@dev-packages/generate-readmes"
-  ]
+  "ignore": ["@dev/helpers", "@dev/prebuild-options", "@dev/generate-readmes"]
 }

.changeset/pre.json

@@ -8,10 +8,7 @@
     "docusaurus-plugin-typedoc": "0.18.0",
     "typedoc-vitepress-theme": "0.0.0",
     "typedoc-github-wiki-theme": "1.0.1",
-    "typedoc-gitlab-wiki-theme": "1.0.0",
-    "@dev-packages/generate-readmes": "0.0.0",
-    "@dev-packages/helpers": "0.0.0",
-    "@dev-packages/prebuild-options": "0.0.0"
+    "typedoc-gitlab-wiki-theme": "1.0.0"
   },
   "changesets": [
     "afraid-fans-study",

dev/examples/README.md

@@ -0,0 +1,6 @@
+These folder is intended for internal dev purposes.
+
+For plugin examples please visit:
+
+- https://github.com/tgreyuk/typedoc-plugin-markdown-examples
+- https://github.com/tgreyuk/typedoc-vitepress-theme-example

examples/docusaurus3/docusaurus.config.js → dev/examples/docusaurus3/docusaurus.config.js

@@ -9,6 +9,7 @@ const docusaurusPlugin = path.join(
   __dirname,
   '..',
   '..',
+  '..',
   'packages',
   'docusaurus-plugin-typedoc',
   'dist',
@@ -45,8 +46,8 @@ const config = {
     [
       docusaurusPlugin,
       {
-        ...require(path.join(__dirname, '../../stubs/typedoc.cjs')),
-        entryPoints: '../../stubs/src/reflections/index.ts',
+        ...require(path.join(__dirname, '../../../stubs/typedoc.cjs')),
+        entryPoints: '../../../stubs/src/reflections/index.ts',
         typeDeclarationFormat: 'table',
         expandObjects: true,
         readme: 'none',
@@ -60,8 +61,8 @@ const config = {
       {
         id: 'api-2',
         out: './docs/api-2',
-        ...require(path.join(__dirname, '../../stubs/typedoc.cjs')),
-        entryPoints: '../../stubs/src/groups/**/*.ts',
+        ...require(path.join(__dirname, '../../../stubs/typedoc.cjs')),
+        entryPoints: '../../../stubs/src/groups/**/*.ts',
         cleanOutputDir: true,
       },
     ],
@@ -70,8 +71,8 @@ const config = {
       {
         id: 'api-3',
         out: './docs/api-3',
-        ...require(path.join(__dirname, '../../stubs/typedoc.cjs')),
-        entryPoints: '../../stubs/src/groups/**/*.ts',
+        ...require(path.join(__dirname, '../../../stubs/typedoc.cjs')),
+        entryPoints: '../../../stubs/src/groups/**/*.ts',
         readme: 'none',
         outputFileStrategy: 'modules',
         entryModule: 'index',
@@ -83,8 +84,8 @@ const config = {
       {
         id: 'api-4',
         out: './docs/api-4',
-        ...require(path.join(__dirname, '../../stubs/typedoc.cjs')),
-        entryPoints: '../../stubs/src/packages/*',
+        ...require(path.join(__dirname, '../../../stubs/typedoc.cjs')),
+        entryPoints: '../../../stubs/src/packages/*',
         entryPointStrategy: 'packages',
         sidebar: { pretty: true },
       },

examples/docusaurus3/package.json → dev/examples/docusaurus3/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
-    "prestart": "cd ../../packages/docusaurus-plugin-typedoc && npm run build",
+    "prestart": "cd ../../../packages/docusaurus-plugin-typedoc && npm run build",
     "start": "docusaurus start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",

examples/vitepress/package.json → dev/examples/vitepress/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "scripts": {
     "publish-typedoc": "typedoc",
-    "build-plugin": "cd ../../packages/typedoc-vitepress-theme && npm run build",
+    "build-plugin": "cd ../../../packages/typedoc-vitepress-theme && npm run build",
     "predocs:dev": "npm run build-plugin && npm run publish-typedoc",
     "docs:dev": "vitepress dev",
     "docs:build": "vitepress build",

dev/examples/vitepress/typedoc.json

@@ -0,0 +1,14 @@
+{
+  "extends": ["../../../stubs/typedoc.cjs"],
+  "entryPoints": ["../../../stubs/src/packages/*"],
+  "entryPointStrategy": "packages",
+  "outputFileStrategy": "modules",
+  "plugin": [
+    "../../../packages/typedoc-plugin-markdown/dist",
+    "../../../packages/typedoc-vitepress-theme/dist"
+  ],
+  "sidebar": {
+    "collapse": false,
+    "pretty": true
+  }
+}

dev-packages/generate-readmes/cli.ts → dev/packages/generate-readmes/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env ts-node
 
-import { DOCS_CONFIG } from '@dev-packages/helpers';
+import { DOCS_CONFIG } from '@dev/helpers';
 import { consola } from 'consola';
 import * as fs from 'fs';
 

dev-packages/generate-readmes/package.json → dev/packages/generate-readmes/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@dev-packages/generate-readmes",
+  "name": "@dev/generate-readmes",
   "version": "0.0.0",
   "private": true,
   "files": [

dev-packages/helpers/package.json → dev/packages/helpers/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@dev-packages/helpers",
+  "name": "@dev/helpers",
   "version": "0.0.0",
   "private": true,
   "main": "src/index.ts",

dev-packages/prebuild-options/cli.ts → dev/packages/prebuild-options/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env ts-node
 
-import { DOCS_CONFIG, DocsConfig, getPackageName } from '@dev-packages/helpers';
+import { DOCS_CONFIG, DocsConfig, getPackageName } from '@dev/helpers';
 import { consola } from 'consola';
 import { generateDocs } from './tasks/generate-docs';
 import { generateModels } from './tasks/generate-models';

dev-packages/prebuild-options/package.json → dev/packages/prebuild-options/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@dev-packages/prebuild-options",
+  "name": "@dev/prebuild-options",
   "version": "0.0.0",
   "private": true,
   "files": [

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

@@ -1,4 +1,4 @@
-import { DocsConfig } from '@dev-packages/helpers/src/models';
+import { DocsConfig } from '@dev/helpers/src/models';
 import * as fs from 'fs';
 import * as path from 'path';
 import { Project, VariableStatement } from 'ts-morph';
@@ -212,7 +212,15 @@ function getExampleValue(option) {
 }
 
 function getDocsPath(docsPath: string) {
-  const pagesPath = path.join(__dirname, '..', '..', '..', 'docs', 'pages');
+  const pagesPath = path.join(
+    __dirname,
+    '..',
+    '..',
+    '..',
+    '..',
+    'docs',
+    'pages',
+  );
   return path.join(pagesPath, docsPath);
 }
 

docs/pages/_meta.json

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

docs/pages/guides/custom-output.mdx → docs/pages/customizing.mdx

@@ -1,34 +1,68 @@
 import { Callout, FileTree } from 'nextra/components';
 
-# Custom Output
+# Customizing 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).
+Output can be customized following an adapted version of TypeDoc's [Custom Theme docs](https://github.com/TypeStrong/typedoc/blob/master/internal-docs/custom-themes.md).
 
-## Local plugins
+Additional functionality is provided by writing a local plugin.
 
-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.
+<Callout type="warning">
+  Examples in this guide are written as ESM, however TypeDoc supports both ESM
+  and CommonJS modules. Please adapt to your own coding preference.
+</Callout>
 
-```js filename="custom-plugin.mjs"
+## Writing a Local plugins
+
+To get started a create a local TypeDoc plugin file. Here we are writing a file in a directory named `local-plugins` and referencing it in `typedoc.json`.
+
+```js filename="local-plugins/my-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.
+  // Additional 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"]
+  "plugin": ["typedoc-plugin-markdown", "./local-plugins/my-custom-plugin.mjs"]
+}
+```
+
+## Consuming Navigtion
+
+If required a navigation structure can be provided to the output. This is useful if you want to provide a custom sidebar or navigation bar.
+
+This can be achieved by adding `postRenderAsyncJobs` to the renderer.
+
+```js filename="local-plugins/my-navigation-plugin.mjs"
+// @ts-check
+
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ */
+export function load(app) {
+  app.renderer.postRenderAsyncJobs.push(
+   /**
+    * @param {import('typedoc-plugin-markdown').MarkdownRendererEvent} output
+    */
+    async (event: MarkdownRendererEvent) => {
+      // The navigation JSON structure is available on the output.
+      const navigation = event.navigation;
+
+      // This can be parsed to something else or written straight to a file:
+      fs.writeFileSync('navigation.json', JSON.stringify(navigation));
+    },
+  );
 }
 ```
 
-## Hooks
+## Utilizing Hooks
 
 Hooks allows Markdown (or HTML) to be injected into the output in specific locations and are the most basic form form of customization.
 
@@ -53,11 +87,11 @@ Available hooks are:
 - `page.end` - Applied at the end of the markdown output.
 - `content.begin` - Applied before the main markdown content is rendered..
 
-## Custom Theme Class
+## Writing a Custom Theme
 
 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.
+In theory all available templates, partials and helpers can be overriden 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.
 

docs/pages/customizing/_meta.json

@@ -0,0 +1,6 @@
+{
+  "local-plugins": "Writing a Local plugin",
+  "navigation": "Consuming Navigtion",
+  "hooks": "Utilizing Hooks",
+  "custom-theme": "Custom Theme"
+}

docs/pages/customizing/custom-theme.mdx

@@ -0,0 +1,44 @@
+# Custom Theme
+
+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 helpers can be overriden 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/customizing/hooks.mdx

@@ -0,0 +1,24 @@
+# Utilizing 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..

docs/pages/customizing/local-plugins.mdx

@@ -0,0 +1,24 @@
+import { Callout, FileTree } from 'nextra/components';
+
+# Writing a Local plugin
+
+To get started a create a local TypeDoc plugin file. Here we are writing a file in a directory named `local-plugins` and referencing it in `typedoc.json`.
+
+```js filename="local-plugins/my-custom-plugin.mjs"
+// @ts-check
+
+/**
+ * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
+ */
+export function load(app) {
+  // Additional 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", "./local-plugins/my-custom-plugin.mjs"]
+}
+```