chore: Refactor docs

.gitignore

@@ -8,7 +8,6 @@ dist
 samples
 out
 typedoc-examples
-plugin-docs
 html
 /devdocs
 /devdocs-html

devtools/packages/helpers/constants.ts

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

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

@@ -86,8 +86,7 @@ export async function generateDocs(docsConfig: DocsConfig) {
       }
       options.forEach((option) => {
         out.push(
-          `${optionLevel} ${
-            Boolean(option.deprecated) ? `~${option.name}~` : `${option.name}`
+          `${optionLevel} ${Boolean(option.deprecated) ? `~${option.name}~` : `${option.name}`
           }`,
         );
         if (Boolean(option.deprecated)) {
@@ -131,12 +130,12 @@ export async function generateDocs(docsConfig: DocsConfig) {
           out.push(`
 \`\`\`json filename="typedoc.json"
 ${JSON.stringify(
-  JSON.parse(`{
+            JSON.parse(`{
   "${option.name}": ${getExampleValue(option)}
 }`),
-  null,
-  2,
-)}
+            null,
+            2,
+          )}
 
 \`\`\``);
         }
@@ -146,7 +145,7 @@ ${JSON.stringify(
   }
 
   const optionDocPath = path.join(
-    getDocsPath(docsConfig.optionsPath),
+    getPagesPath(docsConfig.optionsPath),
     'options.mdx',
   );
 
@@ -212,7 +211,7 @@ function getExampleValue(option) {
   return getDefaultValue(option);
 }
 
-function getDocsPath(docsPath: string) {
+function getPagesPath(docsPath: string) {
   const pagesPath = path.join(
     __dirname,
     '..',

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

@@ -37,15 +37,31 @@ export async function generateModels(declarationsPath: string) {
     }
   }
 
+  /**
+   * Describes the options declared by the plugin.
+   *
+   * @category Options
+   */
   export interface PluginOptions {
     ${(Object.entries(optionsConfig) as any)
-      .map(([name, option]) => `${name}: ${getType(name, option)};`)
+      .map(
+        ([name, option]) => `
+/**
+ * ${option.help}
+ */
+${name}: ${getType(name, option, true)};`,
+      )
       .join('\n')}
   }
 
   ${mixedTypes
     ?.map(([name, option]) => {
       return `
+  /**
+   * ${getComments(name)}
+   *
+   * @category Options
+   */
   export interface ${capitalize(name)} {
       ${Object.entries(option.defaultValue as any)
         .map(
@@ -73,6 +89,13 @@ export async function generateModels(declarationsPath: string) {
   fs.writeFileSync(optionsModelFile, formatted);
 }
 
+function getComments(name: string) {
+  if (name === 'textContentMappings') {
+    return 'Describes the keys available to replace static text.';
+  }
+  return '';
+}
+
 function getValueType(value: any) {
   if (value === true || value === false) {
     return 'boolean';
@@ -83,7 +106,19 @@ function getValueType(value: any) {
   return 'string';
 }
 
-function getType(name: string, option: Partial<DeclarationOption>) {
+function getType(
+  name: string,
+  option: Partial<DeclarationOption>,
+  isInterface = false,
+) {
+  if (option.type === ParameterType.Array && option.defaultValue) {
+    return `(${option.defaultValue
+      .toString()
+      .split(',')
+      .map((item) => `"${item}"`)
+      .join(' | ')})[]`;
+  }
+
   if (option.type === ParameterType.Boolean) {
     return 'boolean';
   }
@@ -100,7 +135,14 @@ function getType(name: string, option: Partial<DeclarationOption>) {
     return 'Record<string, boolean>';
   }
   if (option.type === ParameterType.Mixed && option.defaultValue) {
-    return `ManuallyValidatedOption<${capitalize(name)}>`;
+    const usePartial = name === 'textContentMappings';
+    return isInterface
+      ? usePartial
+        ? `Partial<${capitalize(name)}>`
+        : capitalize(name)
+      : usePartial
+        ? `ManuallyValidatedOption<Partial<${capitalize(name)}>>`
+        : `ManuallyValidatedOption<${capitalize(name)}>`;
   }
 
   if (option.type === ParameterType.Map && option.map) {

docs/components/package-description.jsx

@@ -1,10 +1,16 @@
 import Link from 'next/link';
 
-export const PackageDescription = ({ description }) => {
-  const parts = description.substring(0, description.length - 1).split(' ');
+export const PackageDescription = ({ pjson }) => {
+  const parts = pjson.description
+    .substring(0, pjson.description.length - 1)
+    .split(' ');
 
   return (
-    <p className="nx-mt-6 nx-leading-7">
+    <p className="text-lg">
+      <span className="inline-flex items-center rounded-md bg-gray-50 px-2 py-1 mb-5 mt-3 text-sm font-medium text-gray-600 ring-1 ring-inset ring-gray-500/10">
+        {pjson.version}
+      </span>
+      <br />
       {parts.map((part) => {
         const isLink = [
           'TypeDoc',

docs/styles.css → docs/global.css

@@ -1,3 +1,7 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
 .nextra-toc a[href^='#parameters'],
 .nextra-toc a[href^='#returns'],
 .nextra-toc a[href^='#source'],

docs/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.

docs/next.config.js

@@ -1,9 +1,8 @@
-const withNextra = require('nextra')({
+import nextra from "nextra";
+
+const withNextra = nextra({
   theme: 'nextra-theme-docs',
   themeConfig: './theme.config.jsx',
 });
 
-module.exports = withNextra();
-
-// If you have other Next.js configurations, you can pass them as the parameter:
-// module.exports = withNextra({ /* other next.js config */ })
+export default withNextra();