feat(core): typedoc 0.28 compatibility fixes and enhancements

Author: tgreyuk

.changeset/clear-eagles-taste.md

@@ -0,0 +1,8 @@
+---
+'typedoc-plugin-markdown': minor
+---
+
+- Implemented custom routers for plugin to support TypeDoc 0.28 router implementation.
+- Updated HTML anchors in headings and table rows to be unique, to avoid clashing with any auto generated ids.
+- Added "typeAliasPropertiesFormat" option to support TypeDoc 0.28 updated behaviour for Object literal type alias types.
+- The page header (if displayed) will contain separate links to Readme and index page (if applicable).

.changeset/config.json

@@ -13,6 +13,10 @@
   "ignore": [
     "@devtools/*",
     "typedoc-github-wiki-theme",
-    "typedoc-gitlab-wiki-theme"
+    "typedoc-gitlab-wiki-theme",
+    "typedoc-vitepress-theme",
+    "typedoc-plugin-frontmatter",
+    "docusaurus-plugin-typedoc",
+    "typedoc-plugin-remark"
   ]
 }

.github/workflows/ci.docusaurus-plugin-typedoc.yml

@@ -6,6 +6,10 @@ on:
       - '!packages/docusaurus-plugin-typedoc/README.md'
       - '!packages/docusaurus-plugin-typedoc/CHANGELOG.md'
       - '!packages/docusaurus-plugin-typedoc/package.json'
+    branches:
+      - main
+      - release
+      - beta
   pull_request:
     paths:
       - 'packages/docusaurus-plugin-typedoc/**'

.github/workflows/ci.typedoc-github-wiki-theme.yml

@@ -6,6 +6,10 @@ on:
       - '!packages/typedoc-github-wiki-theme/README.md'
       - '!packages/typedoc-github-wiki-theme/CHANGELOG.md'
       - '!packages/typedoc-github-wiki-theme/package.json'
+    branches:
+      - main
+      - release
+      - beta
   pull_request:
     paths:
       - 'packages/typedoc-github-wiki-theme/**'

.github/workflows/ci.typedoc-gitlab-wiki-theme.yml

@@ -6,6 +6,10 @@ on:
       - '!packages/typedoc-gitlab-wiki-theme/README.md'
       - '!packages/typedoc-gitlab-wiki-theme/CHANGELOG.md'
       - '!packages/typedoc-gitlab-wiki-theme/package.json'
+    branches:
+      - main
+      - release
+      - beta
   pull_request:
     paths:
       - 'packages/typedoc-gitlab-wiki-theme/**'

.github/workflows/ci.typedoc-plugin-frontmatter.yml

@@ -6,6 +6,10 @@ on:
       - '!packages/typedoc-plugin-frontmatter/README.md'
       - '!packages/typedoc-plugin-frontmatter/CHANGELOG.md'
       - '!packages/typedoc-plugin-frontmatter/package.json'
+    branches:
+      - main
+      - release
+      - beta
   pull_request:
     paths:
       - 'packages/typedoc-plugin-frontmatter/**'

.github/workflows/ci.typedoc-plugin-remark.yml

@@ -6,6 +6,10 @@ on:
       - '!packages/typedoc-plugin-remark/README.md'
       - '!packages/typedoc-plugin-remark/CHANGELOG.md'
       - '!packages/typedoc-plugin-remark/package.json'
+    branches:
+      - main
+      - release
+      - beta
   pull_request:
     paths:
       - 'packages/typedoc-plugin-remark/**'

.github/workflows/ci.typedoc-vitepress-theme.yml

@@ -6,6 +6,10 @@ on:
       - '!packages/typedoc-vitepress-theme/README.md'
       - '!packages/typedoc-vitepress-theme/CHANGELOG.md'
       - '!packages/typedoc-vitepress-theme/package.json'
+    branches:
+      - main
+      - release
+      - beta
   pull_request:
     paths:
       - 'packages/typedoc-vitepress-theme/**'

.github/workflows/ci.yml

@@ -10,6 +10,7 @@ on:
     branches:
       - main
       - release
+      - beta
   pull_request:
     paths:
       - 'packages/typedoc-plugin-markdown/**'

.gitignore

@@ -4,6 +4,10 @@
 dist
 .nyc_output/
 
+# yalc
+yalc.lock
+.yalc
+
 # testing
 samples
 typedoc-examples
@@ -15,27 +19,13 @@ html
 node_modules
 
 # IDEs and editors
-/.idea
-.project
-.classpath
-.c9/
-*.launch
 .settings/
 
 # misc
-/.sass-cache
-/connect.lock
-coverage
-/libpeerconnection.log
 npm-debug.log
-testem.log
 /typings
 .npmrc
 
-# e2e
-/e2e/*.js
-/e2e/*.map
-
 #System Files
 .DS_Store
 Thumbs.db

devtools/packages/helpers/constants.ts

@@ -8,6 +8,7 @@ export const DOCS_CONFIG: Record<string, DocsConfig> = {
     declarationsPath: `${process.cwd()}/src/options/declarations.ts`,
     translatablePath: `${process.cwd()}/src/internationalization/locales/en.ts`,
     optionsPath: '/docs',
+    optionsFile: 'options/index.mdx',
     docsPath: '/docs',
     declarations: true,
     presets: false,

devtools/packages/helpers/models.ts

@@ -3,6 +3,7 @@ export interface DocsConfig {
   translatablePath?: string;
   presetsPath?: string;
   optionsPath: string;
+  optionsFile?: string;
   docsPath: string;
   declarations: boolean;
   presets: boolean;

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

@@ -17,7 +17,14 @@ export async function generateOptionsDocs(docsConfig: DocsConfig) {
     tsConfigFilePath: 'tsconfig.json',
   });
 
-  const outputPage: string[] = [`import { Callout } from 'nextra/components';`];
+  const outputPage: string[] = [];
+
+  if (docsConfig.optionsFile === 'options/index.mdx')
+    outputPage.push(`---
+asIndexPage: true
+---`);
+
+  outputPage.push(`import { Callout } from 'nextra/components';`);
 
   outputPage.push('# Options');
   if (docsConfig.docsPath === '/docs') {
@@ -231,6 +238,7 @@ ${JSON.stringify(exampleJson, null, 2)}
         );
         const formattedOut = await prettier.format(out.join('\n\n'), {
           parser: 'mdx',
+          singleQuote: true,
         });
         fs.writeFileSync(catDocPath, formattedOut);
       } else {
@@ -249,6 +257,7 @@ ${JSON.stringify(exampleJson, null, 2)}
         )}`,
         {
           parser: 'typescript',
+          singleQuote: true,
         },
       );
 
@@ -263,11 +272,12 @@ ${JSON.stringify(exampleJson, null, 2)}
 
     const optionDocPath = path.join(
       getPagesPath(docsConfig.optionsPath),
-      'options.mdx',
+      docsConfig.optionsFile || 'options.mdx',
     );
 
     const formattedOut = await prettier.format(outputPage.join('\n\n'), {
       parser: 'mdx',
+      singleQuote: true,
     });
 
     fs.writeFileSync(optionDocPath, formattedOut);
@@ -364,7 +374,7 @@ function getPagesPath(docsPath: string) {
     '..',
     '..',
     'docs',
-    'pages',
+    'content',
   );
   return path.join(pagesPath, docsPath);
 }

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

@@ -66,18 +66,24 @@ import { ManuallyValidatedOption } from 'typedoc';${docsConfig.optionsPath === '
         theme_default_value: [];
         theme_default_type: [];
         theme_description: [];
+        theme_documentation: [];
+        theme_category: [];
+        theme_categories: [];
         theme_event: [];
         theme_re_exports: [];
         theme_renames_and_re_exports: [];
         theme_extends: [];
         theme_extended_by: [];
         theme_globals: [];
+        theme_group: [];
+        theme_groups: [];
         theme_member: [];
         theme_member_plural: [];
         theme_modifier: [];
         theme_name: [];
         theme_package: [];
         theme_packages: [];
+        theme_readme: [];
         theme_type: [];
         theme_value: [];
         theme_version: [];

devtools/packages/testing/index.ts

@@ -3,7 +3,12 @@ import * as path from 'path';
 
 export function expectFileToEqual(
   key: string,
-  outputFileStrategy: 'modules' | 'members' | ('modules' | 'members')[],
+  outputFileStrategy:
+    | 'modules'
+    | 'members'
+    | 'categories'
+    | 'groups'
+    | ('modules' | 'members')[],
   file: string | string[],
   limit?: number,
   range?: Array<number>,
@@ -41,7 +46,7 @@ export function expectFileToEqual(
 
 export function expectUrlsToEqual(
   outDir: string,
-  outputFileStrategies: ('modules' | 'members')[],
+  outputFileStrategies: ('members' | 'modules' | 'categories' | 'groups')[],
 ) {
   outputFileStrategies.forEach((outputFileStrategy) => {
     const basePath = getBasePath(outDir, outputFileStrategy);
@@ -78,7 +83,10 @@ export function expectUrlsToEqual(
   });
 }
 
-function getBasePath(key: string, outputFileStrategy: 'modules' | 'members') {
+function getBasePath(
+  key: string,
+  outputFileStrategy: 'modules' | 'members' | 'categories' | 'groups',
+) {
   const basePath = path.join(
     process.cwd(),
     'test',

docs/app/[[...mdxPath]]/page.jsx

@@ -0,0 +1,43 @@
+import { generateStaticParamsFor, importPage } from 'nextra/pages';
+import * as path from 'path';
+import '../../globals.css';
+import { useMDXComponents as getMDXComponents } from '../../mdx-components';
+
+export const generateStaticParams = generateStaticParamsFor('mdxPath');
+
+export async function generateMetadata(props) {
+  const params = await props.params;
+
+  const { metadata } = await importPage(params.mdxPath);
+
+  const titlePath = metadata.filePath
+    .split(path.sep)
+    .map((part) => part[0]?.toUpperCase() + part.substring(1))
+    .slice(1, metadata.asIndexPage ? -2 : -1)
+    .filter((part) => Boolean(part))
+    .join(' • ');
+
+  const titleParts = [];
+  if (titlePath) {
+    titleParts.push(titlePath);
+  }
+  titleParts.push(metadata.title);
+  const title = `typedoc-plugin-markdown • ${titleParts.join(' • ')}`;
+  return {
+    ...metadata,
+    title,
+  };
+}
+
+const Wrapper = getMDXComponents().wrapper;
+
+export default async function Page(props) {
+  const params = await props.params;
+  const result = await importPage(params.mdxPath);
+  const { default: MDXContent, toc, metadata } = result;
+  return (
+    <Wrapper toc={toc} metadata={metadata}>
+      <MDXContent {...props} params={params} />
+    </Wrapper>
+  );
+}

docs/pages/_meta.js renamed to docs/app/_meta.js

@@ -7,7 +7,7 @@ export default {
       breadcrumb: false,
       sidebar: false,
       footer: false,
-      layout: 'raw',
+      timestamp: false,
     },
   },
   docs: {

docs/app/layout.tsx

@@ -0,0 +1,64 @@
+import { faMarkdown } from '@fortawesome/free-brands-svg-icons';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+
+import { Footer, Layout, Navbar } from 'nextra-theme-docs';
+import 'nextra-theme-docs/style.css';
+import { Head } from 'nextra/components';
+import { getPageMap } from 'nextra/page-map';
+import '../globals.css';
+
+export const metadata = {
+  // Define your metadata here
+  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
+};
+
+const navbar = (
+  <Navbar
+    logo={
+      <div style={{ display: 'flex', alignItems: 'center' }}>
+        <div style={{ width: '26px', height: '18px' }}>
+          <FontAwesomeIcon
+            icon={faMarkdown}
+            width={'26px'}
+            size="sm"
+            style={{ width: '100%', height: '100%' }}
+          />
+        </div>
+        <div
+          style={{
+            marginLeft: '6px',
+            fontSize: '14px',
+            fontWeight: 'bold',
+          }}
+        >
+          typedoc-plugin-markdown
+        </div>
+      </div>
+    }
+    projectLink="https://github.com/typedoc2md/typedoc-plugin-markdown"
+  />
+);
+const footer = <Footer></Footer>;
+
+export default async function RootLayout({ children }) {
+  return (
+    <html lang="en" dir="ltr" suppressHydrationWarning>
+      <Head>
+        <link rel="icon" href="/logos/markdown-logo.svg" type="image/png" />
+      </Head>
+      <body>
+        <Layout
+          docsRepositoryBase="https://github.com/typedoc2md/typedoc-plugin-markdown/tree/main/docs"
+          navbar={navbar}
+          sidebar={{ defaultMenuCollapseLevel: 1 }}
+          pageMap={await getPageMap()}
+          footer={footer}
+          editLink={''}
+          feedback={{ content: '' }}
+        >
+          {children}
+        </Layout>
+      </body>
+    </html>
+  );
+}

docs/components/option-link.jsx

@@ -3,10 +3,10 @@ import Link from 'next/link';
 export const OptionLink = ({ type, name }) => {
   return (
     <Link
-      href={`/docs/options/${type}-options#--${name.toLowerCase()}`}
+      href={`/docs/options/${type}-options#${name.toLowerCase()}`}
       className="whitespace-nowrap _text-primary-600 _underline _decoration-from-font [text-underline-position:from-font]"
     >
-      <code class="nextra-code">--{name}</code>
+      <code class="nextra-code">{name}</code>
     </Link>
   );
 };