docs: add anchor link to reference parameters (#6194)

- Added anchor links to items in parameter components
- Added sectionTitle prop in markdown theme

Note: Due to the second point, the change requires generating references to see the anchor links, which would result in a big diff in this PR. Instead, next time the references are generated for a release, this feature will available for use.

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/parameter-component.ts

@@ -8,7 +8,10 @@ import { formatParameterComponent } from "../../utils/format-parameter-component
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "parameterComponent",
-    function (this: ReflectionParameterType[]) {
+    function (
+      this: ReflectionParameterType[],
+      options: Handlebars.HelperOptions
+    ) {
       const { parameterComponent, maxLevel, parameterComponentExtraProps } =
         theme.getFormattingOptionsForLocation()
       const parameters = this.reduce(
@@ -26,6 +29,7 @@ export default function (theme: MarkdownTheme) {
         parameterComponent,
         componentItems: parameters,
         extraProps: parameterComponentExtraProps,
+        sectionTitle: options.hash.sectionTitle,
       })
     }
   )

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/parameter.ts

@@ -5,13 +5,13 @@ import { ParameterReflection } from "typedoc"
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "parameter",
-    function (this: ParameterReflection[]) {
+    function (this: ParameterReflection[], options: Handlebars.HelperOptions) {
       const { parameterStyle } = theme.getFormattingOptionsForLocation()
 
       if (parameterStyle === "list") {
         return Handlebars.helpers.parameterList.call(this)
       } else if (parameterStyle === "component") {
-        return Handlebars.helpers.parameterComponent.call(this)
+        return Handlebars.helpers.parameterComponent.call(this, options)
       } else {
         return Handlebars.helpers.parameterTable.call(this)
       }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/react-query-hook-params.ts

@@ -10,7 +10,11 @@ export default function () {
       const hookParameters = getHookParams(this)
 
       if (hookParameters?.length) {
-        parametersStr = Handlebars.helpers.parameter.call(hookParameters)
+        parametersStr = Handlebars.helpers.parameter.call(hookParameters, {
+          hash: {
+            sectionTitle: this.name,
+          },
+        })
       }
 
       return parametersStr

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/react-query-mutation-params.ts

@@ -31,6 +31,7 @@ export default function (theme: MarkdownTheme) {
         parameterComponent,
         componentItems: mutationParameters,
         extraProps: parameterComponentExtraProps,
+        sectionTitle: this.name,
       })
     }
   )

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/react-query-mutation-return.ts

@@ -31,6 +31,7 @@ export default function (theme: MarkdownTheme) {
         parameterComponent,
         componentItems: mutationParameters,
         extraProps: parameterComponentExtraProps,
+        sectionTitle: this.name,
       })
     }
   )

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/react-query-query-return.ts

@@ -31,6 +31,7 @@ export default function (theme: MarkdownTheme) {
         parameterComponent,
         componentItems: mutationParameters,
         extraProps: parameterComponentExtraProps,
+        sectionTitle: this.name,
       })
     }
   )

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/returns.ts

@@ -13,7 +13,7 @@ export default function (theme: MarkdownTheme) {
       if (reflection.variant === "signature" && "type" in reflection) {
         return getReturnFromType(theme, reflection)
       } else if (reflection.comment) {
-        return getReturnFromComment(theme, reflection.comment)
+        return getReturnFromComment(theme, reflection.comment, reflection.name)
       } else {
         return ""
       }
@@ -49,6 +49,7 @@ function getReturnFromType(
       parameterComponent,
       componentItems,
       extraProps: parameterComponentExtraProps,
+      sectionTitle: reflection.name,
     })
   } else {
     return formatReturnAsList(componentItems)
@@ -77,7 +78,11 @@ function formatReturnAsList(componentItems: Parameter[], level = 1): string {
     .join("\n")
 }
 
-function getReturnFromComment(theme: MarkdownTheme, comment: Comment) {
+function getReturnFromComment(
+  theme: MarkdownTheme,
+  comment: Comment,
+  reflectionName: string
+) {
   const md: string[] = []
   const {
     parameterStyle,
@@ -113,6 +118,7 @@ function getReturnFromComment(theme: MarkdownTheme, comment: Comment) {
                       ...parameterComponentExtraProps,
                       title: commentPart.target.name,
                     },
+                    sectionTitle: reflectionName,
                   })}\n\n`
                 : `\n\n<details>\n<summary>\n${
                     commentPart.target.name

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type-declaration-members.ts

@@ -10,7 +10,10 @@ import { formatParameterComponent } from "../../utils/format-parameter-component
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "typeDeclarationMembers",
-    function (this: DeclarationReflection[]) {
+    function (
+      this: DeclarationReflection[],
+      options: Handlebars.HelperOptions
+    ) {
       const { parameterComponent, maxLevel, parameterComponentExtraProps } =
         theme.getFormattingOptionsForLocation()
       const comments = this.map(
@@ -24,6 +27,10 @@ export default function (theme: MarkdownTheme) {
         []
       ) as DeclarationReflection[]
 
+      // if (typeof options.hash.sectionTitle !== "string") {
+      //   console.log("here2")
+      // }
+
       let result = ""
       switch (theme.objectLiteralTypeDeclarationStyle) {
         case "list": {
@@ -36,6 +43,7 @@ export default function (theme: MarkdownTheme) {
             parameterComponent,
             maxLevel,
             parameterComponentExtraProps,
+            sectionTitle: options.hash.sectionTitle,
           })
           break
         }
@@ -65,11 +73,13 @@ function getComponentMarkdownContent({
   parameterComponent,
   maxLevel,
   parameterComponentExtraProps,
+  sectionTitle,
 }: {
   properties: DeclarationReflection[]
   parameterComponent?: string
   maxLevel?: number | undefined
   parameterComponentExtraProps?: Record<string, unknown>
+  sectionTitle: string
 }) {
   const parameters = properties.map((property) =>
     reflectionFormatter({
@@ -84,6 +94,7 @@ function getComponentMarkdownContent({
     parameterComponent,
     componentItems: parameters as Parameter[],
     extraProps: parameterComponentExtraProps,
+    sectionTitle,
   })
 }
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type-parameter-component.ts

@@ -7,7 +7,10 @@ import { formatParameterComponent } from "../../utils/format-parameter-component
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "typeParameterComponent",
-    function (this: TypeParameterReflection[]) {
+    function (
+      this: TypeParameterReflection[],
+      options: Handlebars.HelperOptions
+    ) {
       const { parameterComponent, maxLevel, parameterComponentExtraProps } =
         theme.getFormattingOptionsForLocation()
       const parameters = this.map((parameter) =>
@@ -18,10 +21,15 @@ export default function (theme: MarkdownTheme) {
         })
       )
 
+      // if (typeof options.hash.sectionTitle !== "string") {
+      //   console.log("here3")
+      // }
+
       return formatParameterComponent({
         parameterComponent,
         componentItems: parameters,
         extraProps: parameterComponentExtraProps,
+        sectionTitle: options.hash.sectionTitle,
       })
     }
   )

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/type-parameter.ts

@@ -5,13 +5,16 @@ import { TypeParameterReflection } from "typedoc"
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "typeParameter",
-    function (this: TypeParameterReflection[]) {
+    function (
+      this: TypeParameterReflection[],
+      options: Handlebars.HelperOptions
+    ) {
       const { parameterStyle } = theme.getFormattingOptionsForLocation()
 
       if (parameterStyle === "list") {
         return Handlebars.helpers.typeParameterList.call(this)
       } else if (parameterStyle === "component") {
-        return Handlebars.helpers.typeParameterComponent.call(this)
+        return Handlebars.helpers.typeParameterComponent.call(this, options)
       } else {
         return Handlebars.helpers.typeParameterTable.call(this)
       }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.declaration.hbs

@@ -24,7 +24,7 @@
 
 {{#with typeParameters}}
 
-{{{typeParameter}}}
+{{{typeParameter sectionTitle=../name}}}
 
 {{/with}}
 
@@ -92,7 +92,7 @@
 
 {{#with type.declaration.children}}
 
-{{{typeDeclarationMembers}}}
+{{{typeDeclarationMembers sectionTitle=../name}}}
 
 {{/with}}
 
@@ -118,7 +118,7 @@
 
 {{{titleLevel}}} Properties
 
-{{{typeDeclarationMembers}}}
+{{{typeDeclarationMembers sectionTitle=../name}}}
 
 {{/with}}
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.react-query.signature.hbs

@@ -38,7 +38,7 @@
 
 {{#with typeParameters}}
 
-{{{typeParameter}}}
+{{{typeParameter sectionTitle=../name}}}
 
 {{/with}}
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.signature.hbs

@@ -38,7 +38,7 @@
 
 {{#with typeParameters}}
 
-{{{typeParameter}}}
+{{{typeParameter sectionTitle=../name}}}
 
 {{/with}}
 
@@ -54,7 +54,7 @@
 
 {{#with parameters}}
 
-{{{parameter}}}
+{{{parameter sectionTitle=../name}}}
 
 {{/with}}
 
@@ -106,7 +106,7 @@
 
 {{#with declaration.children}}
 
-{{{typeDeclarationMembers}}}
+{{{typeDeclarationMembers sectionTitle=../../name}}}
 
 {{/with}}
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/members.group.hbs

@@ -34,7 +34,7 @@ ___
 
 {{#with children}}
 
-{{{parameterComponent}}}
+{{{parameterComponent sectionTitle=../owningReflection.name}}}
 
 {{/with}}
 
@@ -86,7 +86,7 @@ ___
 
 {{#with children}}
 
-{{{parameterComponent}}}
+{{{parameterComponent sectionTitle=../owningReflection.name}}}
 
 {{/with}}
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/templates/reflection.hbs

@@ -32,7 +32,7 @@
 
 {{#with model.typeParameters}}
 
-{{{typeParameter}}}
+{{{typeParameter sectionTitle=../model.name}}}
 
 {{/with}}
 

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/format-parameter-component.ts

@@ -3,6 +3,7 @@ import { Parameter } from "../types"
 type FormatParameterComponentProps = {
   parameterComponent: string | undefined
   componentItems: Parameter[]
+  sectionTitle: string
   extraProps?: Record<string, unknown>
 }
 
@@ -43,6 +44,7 @@ export function formatParameterComponent({
   parameterComponent,
   componentItems,
   extraProps,
+  sectionTitle,
 }: FormatParameterComponentProps): string {
   let extraPropsArr: string[] = []
   if (extraProps) {
@@ -54,5 +56,5 @@ export function formatParameterComponent({
   componentItems = sortComponentItems(componentItems)
   return `<${parameterComponent} parameters={${JSON.stringify(
     componentItems
-  )}} ${extraPropsArr.join(" ")}/>`
+  )}} ${extraPropsArr.join(" ")} sectionTitle="${sectionTitle}"/>`
 }