chore(docs): updated frontmatter docs

typedoc2md · Sep 12, 2024 · e64a6ef · e64a6ef
1 parent ae4f1a9
commit e64a6ef
Show file tree

Hide file tree

Showing 8 changed files with 123 additions and 94 deletions.
diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/package.json b/docs/package.json
@@ -20,7 +20,7 @@
     "@fortawesome/free-solid-svg-icons": "^6.6.0",
     "@fortawesome/react-fontawesome": "^0.2.2",
     "@vercel/analytics": "^1.3.1",
-    "next": "^14.2.8",
+    "next": "^14.2.11",
     "nextra": "3.0.0-alpha.36",
     "nextra-theme-docs": "3.0.0-alpha.36",
     "react": "^18.3.1",
@@ -30,9 +30,9 @@
     "@types/node": "^22.5.4",
     "autoprefixer": "^10.4.20",
     "copyfiles": "^2.4.1",
-    "eslint": "^9.9.1",
+    "eslint": "^9.10.0",
     "postcss": "^8.4.45",
-    "tailwindcss": "^3.4.10"
+    "tailwindcss": "^3.4.11"
   },
   "postcss": {
     "plugins": {

diff --git a/docs/pages/plugins/frontmatter/_meta.js b/docs/pages/plugins/frontmatter/_meta.js
@@ -2,4 +2,5 @@ export default {
   'quick-start': '',
   options: '',
   customizing: '',
+  ['block-tags-warning']: 'Block Tags Warning',
 };
diff --git a/docs/pages/plugins/frontmatter/block-tags-warning.mdx b/docs/pages/plugins/frontmatter/block-tags-warning.mdx
@@ -0,0 +1,46 @@
+# Block Tags Warning
+
+If using a custom tag, TypeDoc (since 0.26) will generate the following warning:
+
+```shell
+[warning] Encountered an unknown block tag @description
+```
+
+To suppress this warning you have two options.
+
+#### 1. Using the `--blockTags` TypeDoc option:
+
+You can extend the tag defaults by using a JavaScript configuration file:
+
+```ts
+import { OptionDefaults } from 'typedoc';
+
+const config = {
+  blockTags: [...OptionDefaults.blockTags, '@description', '@author'],
+};
+```
+
+See https://typedoc.org/options/comments/#blocktags.
+
+#### 2. Adding a `tsdoc.json` file:
+
+You add a `tsdoc.json` file next to your `tsconfig.json` file and include the `@source` tag name.
+
+```json
+{
+  "$schema": "https://developer.microsoft.com/en-us/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": ["typedoc/tsdoc.json"],
+  "tagDefinitions": [
+    {
+      "tagName": "@description",
+      "syntaxKind": "block"
+    },
+    {
+      "tagName": "@author",
+      "syntaxKind": "block"
+    }
+  ]
+}
+```
+
+See https://typedoc.org/options/configuration/#tsconfig.
diff --git a/docs/pages/plugins/frontmatter/options.mdx b/docs/pages/plugins/frontmatter/options.mdx
@@ -64,7 +64,7 @@ sidebar: true
   Specify which comment block tags should be added to frontmatter.
 </Callout>
 
-> Accepts an Array.
+> Accepts an array of string values.
 
 Frontmatter variables can be added by extracting comments from block (@) tags.
 
@@ -85,21 +85,6 @@ description: A description that will be added to frontmatter.
 ---
 ```
 
-In addition any non standard tags should be added to a `tsdoc.json` file and added next to your `tsconfig.json` file.
-
-```json filename="tsdoc.json"
-{
-  "$schema": "https://developer.microsoft.com/en-us/json-schemas/tsdoc/v0/tsdoc.schema.json",
-  "extends": ["typedoc/tsdoc.json"],
-  "tagDefinitions": [
-    {
-      "tagName": "@customTag",
-      "syntaxKind": "modifier"
-    }
-  ]
-}
-```
-
 ```json filename="typedoc.json"
 {
   "frontmatterCommentTags": ["author", "description"]

diff --git a/packages/typedoc-plugin-frontmatter/src/_typedoc.d.ts b/packages/typedoc-plugin-frontmatter/src/_typedoc.d.ts
@@ -5,7 +5,7 @@ import { IndexFrontmatter } from './types/options';
 import { ReadmeFrontmatter } from './types/options';
 declare module 'typedoc' {
   export interface TypeDocOptionMap {
-    frontmatterCommentTags: any[];
+    frontmatterCommentTags: string[];
     frontmatterGlobals: ManuallyValidatedOption<FrontmatterGlobals>;
     frontmatterNamingConvention: 'camelCase' | 'snakeCase';
     indexFrontmatter: ManuallyValidatedOption<IndexFrontmatter>;

diff --git a/packages/typedoc-plugin-frontmatter/src/options/declarations.ts b/packages/typedoc-plugin-frontmatter/src/options/declarations.ts
@@ -54,22 +54,7 @@ export const indexFrontmatter: Partial<DeclarationOption> = {
  * author: Joe Bloggs
  * description: A description that will be added to frontmatter.
  * ---
- * ```
- *
- * In addition any non standard tags should be added to a `tsdoc.json` file and added next to your `tsconfig.json` file.
- *
- * ```json filename="tsdoc.json"
- * {
- *   "$schema": "https://developer.microsoft.com/en-us/json-schemas/tsdoc/v0/tsdoc.schema.json",
- *   "extends": ["typedoc/tsdoc.json"],
- *   "tagDefinitions": [
- *       {
- *           "tagName": "@customTag",
- *           "syntaxKind": "modifier"
- *       }
- *   ]
- * }
- * ```
+ * ````
  *
  * @example ["author", "description"]
  */