chore(docs): added troubleshooting docs page

tgreyuk · tgreyuk · commit c8e8c43d8ffb · 2025-04-30T00:35:24.000+01:00
diff --git a/devtools/packages/prebuild-options/tasks/generate-docs.ts b/devtools/packages/prebuild-options/tasks/generate-docs.ts
@@ -29,9 +29,7 @@ asIndexPage: true
   outputPage.push('# Plugin Options');
   if (docsConfig.docsPath === '/docs') {
     outputPage.push(
-      `This page documents additional options that are exposed by this plugin.
-
-*Note: The options must be set at root level and will be ignored inside [packageOptions](https://typedoc.org/documents/Options.Package_Options.html).*`,
+      `This page documents additional options that are exposed by this plugin.`,
     );
   } else {
     if (docsConfig.presets) {
@@ -145,10 +143,10 @@ ${presetsJson}
           ? `import { Callout, FileTree } from 'nextra/components';`
           : '',
       ];
-      const optionLevel =
-        categories.length === 1 && !docsConfig.presets ? '##' : '###';
+      let optionLevel = categories.length > 1 ? '##' : '###';
       if (categories.length > 1) {
         out.push(`# ${getDocsTitle(categoryName)}`);
+        optionLevel = '##';
         if (Object.keys(categoryDescriptions)?.length) {
           out.push(categoryDescriptions[categoryName]);
         }
diff --git a/docs/app/layout.tsx b/docs/app/layout.tsx
@@ -41,7 +41,7 @@ const footer = <Footer></Footer>;
 
 export default async function RootLayout({ children }) {
   return (
-    <html lang="en" dir="ltr" suppressHydrationWarning>
+    <html lang="en" dir="ltr">
       <Head>
         <link rel="icon" href="/logos/markdown-logo.svg" type="image/png" />
       </Head>
diff --git a/docs/components/option-link.jsx b/docs/components/option-link.jsx
@@ -1,12 +1,10 @@
-import Link from 'next/link';
-
 export const OptionLink = ({ type, name }) => {
   return (
-    <Link
+    <a
       href={`/docs/options/${type}-options#${name.toLowerCase()}`}
-      className="whitespace-nowrap _text-primary-600 _underline _decoration-from-font [text-underline-position:from-font]"
+      className="x:focus-visible:nextra-focus x:text-primary-600 x:underline x:hover:no-underline x:decoration-from-font x:[text-underline-position:from-font]"
     >
-      <code class="nextra-code">{name}</code>
-    </Link>
+      <code className="nextra-code">{name}</code>
+    </a>
   );
 };
diff --git a/docs/components/package-description.jsx b/docs/components/package-description.jsx
diff --git a/docs/components/package-version.jsx b/docs/components/package-version.jsx
@@ -1,15 +1,11 @@
-import { readFileSync } from 'fs';
-import * as path from 'path';
+import { packageVersions } from '../utils/package-versions';
+
+export function PackageVersion({ name }) {
+  const version = packageVersions[name];
 
-export async function PackageVersion({ name }) {
-  const packageJsonPath = path.join(
-    process.cwd(),
-    `../packages/${name}/package.json`,
-  );
-  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
   return (
     <strong className="inline-flex items-center rounded-md bg-gray-100 px-2 py-1 mt-3 text-sm font-bold text-gray-600 ring-1 ring-inset ring-gray-500/10">
-      Version: {packageJson.version}
+      Version: {version}
     </strong>
   );
 }
diff --git a/docs/content/docs/_meta.js b/docs/content/docs/_meta.js
@@ -19,6 +19,7 @@ export default {
     type: 'separator',
     title: 'Support',
   },
+  troubleshooting: '',
   versioning: '',
   CHANGELOG: 'Changelog',
   'migration-guide': 'Migration Guide (v4)',
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
@@ -2,9 +2,10 @@
 title: 'Introduction'
 ---
 
-import { Cards, Callout } from 'nextra/components';
-import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+{/* prettier-ignore */}
 import { faGithub } from '@fortawesome/free-brands-svg-icons';
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import { Callout, Cards } from 'nextra/components';
 
 # typedoc-plugin-markdown
 
diff --git a/docs/content/docs/options/index.mdx b/docs/content/docs/options/index.mdx
@@ -8,8 +8,6 @@ import { Callout } from 'nextra/components';
 
 This page documents additional options that are exposed by this plugin.
 
-_Note: The options must be set at root level and will be ignored inside [packageOptions](https://typedoc.org/documents/Options.Package_Options.html)._
-
 ## File Options
 
 Options that are used by the plugin's [routers](/docs/output-file-structure) to configure how files are output.
diff --git a/docs/content/docs/troubleshooting.mdx b/docs/content/docs/troubleshooting.mdx
@@ -0,0 +1,59 @@
+# Troubleshooting
+
+This guide covers common issues you may encounter when using the typedoc-plugin-markdown, along with solutions and explanations.
+
+## TypeDoc Loaded Multiple Times
+
+**Symptom:**
+
+You're running TypeDoc and see the following error which is preventing docs from being generated:
+
+> **[warning] TypeDoc has been loaded multiple times. This is commonly caused by plugins which have their own installation of TypeDoc.**
+
+**Why?**:
+
+This plugin declares TypeDoc as a peer dependency, so it won't install TypeDoc automatically.
+
+If you're running TypeDoc in a standard setup and you're seeing this warning, your package manager is likely resolving dependencies in a way that causes multiple instances of TypeDoc to be loaded.
+
+When installing globally, be aware of [npm/cli#7057](https://github.com/npm/cli/issues/7057).
+
+**Solution:**
+
+Use the `--legacy-peer-deps` flag when installing packages.
+
+## `packageOptions` Not Working
+
+**Symptom:**
+
+You are setting options inside `packageOptions`, but they are being ignored.
+
+**Why?**
+
+The `packageOptions` field only applies to conversion options. Options exposed by this plugin apply during rendering, not conversion. That's why they won't work if placed inside `packageOptions`.
+
+**Solution:**
+
+Place all plugin specific options at the root level of your TypeDoc configuration.
+
+See [TypeDoc packageOptions](https://typedoc.org/documents/Options.Package_Options.html).
+
+## MDX Compilation Failed
+
+**Symptom:**
+
+You're using an MDX parser and see this error (or similar):
+
+> **Error: MDX compilation failed**
+>
+> Cause: Could not parse expression with acorn
+
+**Why?**
+
+This is almost certainly caused by invalid MDX syntax in doc comments.
+
+**Solution:**
+
+- Wrap invalid MDX in backticks to treat it as a code block.
+- Enable <OptionLink type="utility" name="sanitizeComments" /> to automatically escape problematic characters.
+- Switch to CommonMark, if supported by your parser.
diff --git a/docs/mdx-components.js b/docs/mdx-components.js
@@ -1,6 +1,5 @@
 import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs';
 import { OptionLink } from './components/option-link';
-import { PackageDescription } from './components/package-description';
 import { PackageVersion } from './components/package-version';
 
 // Get the default MDX components
@@ -11,7 +10,6 @@ export function useMDXComponents(components) {
   return {
     ...themeComponents,
     ...components,
-    PackageDescription,
     PackageVersion,
     OptionLink,
   };
diff --git a/docs/utils/package-versions.ts b/docs/utils/package-versions.ts
@@ -0,0 +1,17 @@
+import { readFileSync } from 'fs';
+import path from 'path';
+
+function getVersion(name: string): string {
+  const packageJsonPath = path.join(
+    process.cwd(),
+    '../packages',
+    name,
+    'package.json',
+  );
+  const json = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+  return json.version;
+}
+
+export const packageVersions = {
+  'typedoc-plugin-markdown': getVersion('typedoc-plugin-markdown'),
+};
