docs: TSDoc + reference of fulfillment service (#5761)

docs-util/packages/scripts/package.json

@@ -33,7 +33,7 @@
     "typedoc-plugin-missing-exports": "^2.1.0",
     "typedoc-plugin-reference-excluder": "1.1.3",
     "typedoc-plugin-rename-defaults": "^0.6.6",
-    "typescript": "^5.2.2"
+    "typescript": "5.2"
   },
   "devDependencies": {
     "@types/randomcolor": "^0.5.8"

docs-util/packages/typedoc-config/fulfillment.js

@@ -0,0 +1,64 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const path = require("path")
+const globalTypedocOptions = require("./_base")
+
+const pathPrefix = path.join(__dirname, "..", "..", "..")
+
+module.exports = {
+  ...globalTypedocOptions,
+  entryPoints: [
+    path.join(
+      pathPrefix,
+      "packages/medusa/src/interfaces/fulfillment-service.ts"
+    ),
+  ],
+  out: [path.join(pathPrefix, "www/apps/docs/content/references/fulfillment")],
+  tsconfig: path.join(__dirname, "extended-tsconfig", "medusa.json"),
+  name: "Fulfillment Provider Reference",
+  indexTitle: "Fulfillment Provider Reference",
+  entryDocument: "_index.mdx",
+  hideInPageTOC: true,
+  hideBreadcrumbs: true,
+  formatting: {
+    "*": {
+      showCommentsAsHeader: true,
+      sections: {
+        member_sources_definedIn: false,
+        reflection_hierarchy: false,
+        member_sources_inheritedFrom: false,
+        member_sources_implementationOf: false,
+        reflection_implementedBy: false,
+        member_signature_sources: false,
+        reflection_callable: false,
+        reflection_indexable: false,
+        reflection_implements: false,
+        member_signature_title: false,
+        member_signature_returns: false,
+      },
+      parameterStyle: "component",
+      parameterComponent: "ParameterTypes",
+      mdxImports: [
+        `import ParameterTypes from "@site/src/components/ParameterTypes"`,
+      ],
+      reflectionGroups: {
+        Properties: false,
+      },
+      frontmatterData: {
+        displayed_sidebar: "modules",
+      },
+    },
+    AbstractFulfillmentService: {
+      reflectionDescription: `In this document, you’ll learn how to create a fulfillment provider to a Medusa backend and the methods you must implement in it. If you’re unfamiliar with the Shipping architecture in Medusa, make sure to [check out the overview first](https://docs.medusajs.com/modules/carts-and-checkout/shipping).`,
+      frontmatterData: {
+        displayed_sidebar: "modules",
+        slug: "/modules/carts-and-checkout/backend/add-fulfillment-provider",
+      },
+      reflectionTitle: {
+        fullReplacement: "How to Create a Fulfillment Provider",
+      },
+    },
+  },
+  objectLiteralTypeDeclarationStyle: "component",
+  mdxOutput: true,
+  maxLevel: 2,
+}

docs-util/packages/typedoc-plugin-custom/package.json

@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "@types/node": "^16.11.10",
-    "typescript": "^4.6"
+    "typescript": "5.2"
   },
   "keywords": [
     "typedocplugin",

docs-util/packages/typedoc-plugin-markdown-medusa/package.json

@@ -23,7 +23,7 @@
   "devDependencies": {
     "@types/node": "^16.11.10",
     "copyfiles": "^2.4.1",
-    "typescript": "^4.6"
+    "typescript": "5.2"
   },
   "keywords": [
     "typedocplugin",

docs-util/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -45,6 +45,10 @@ import commentTagHelper from "./resources/helpers/comment-tag"
 import exampleHelper from "./resources/helpers/example"
 import ifFeatureFlagHelper from "./resources/helpers/if-feature-flag"
 import featureFlagHelper from "./resources/helpers/feature-flag"
+import decrementCurrentTitleLevelHelper from "./resources/helpers/decrement-current-title-level"
+import incrementCurrentTitleLevelHelper from "./resources/helpers/increment-current-title-level"
+import hasMoreThanOneSignatureHelper from "./resources/helpers/has-more-than-one-signature"
+import ifCanShowConstructorsTitleHelper from "./resources/helpers/if-can-show-constructors-title"
 import { MarkdownTheme } from "./theme"
 
 // test
@@ -120,4 +124,8 @@ export function registerHelpers(theme: MarkdownTheme) {
   exampleHelper()
   ifFeatureFlagHelper()
   featureFlagHelper()
+  decrementCurrentTitleLevelHelper(theme)
+  incrementCurrentTitleLevelHelper(theme)
+  hasMoreThanOneSignatureHelper()
+  ifCanShowConstructorsTitleHelper()
 }

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

@@ -6,7 +6,7 @@ import { MarkdownTheme } from "../../theme"
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
     "commentTag",
-    function (tag: CommentTag, commentLevel = 4, parent = null) {
+    function (tag: CommentTag, parent = null) {
       const { showCommentsAsHeader, showCommentsAsDetails } =
         theme.getFormattingOptionsForLocation()
       if (tag.tag === "@schema") {
@@ -19,8 +19,7 @@ export default function (theme: MarkdownTheme) {
 
       if (showCommentsAsHeader) {
         return `${Handlebars.helpers.titleLevel.call(
-          parent,
-          commentLevel
+          parent
         )} ${tagTitle}\n\n${tagContent}`
       } else if (showCommentsAsDetails) {
         return `<details>\n<summary>\n${tagTitle}\n</summary>\n\n${tagContent}\n\n</details>`

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

@@ -10,7 +10,6 @@ export default function () {
       comment: Comment,
       showSummary = true,
       showTags = true,
-      commentLevel = 4,
       parent = null
     ) {
       const md: string[] = []
@@ -24,11 +23,7 @@ export default function () {
           (tag) => !EXCLUDED_TAGS.includes(tag.tag)
         )
         const tags = filteredTags.map((tag) => {
-          return Handlebars.helpers.commentTag(
-            tag,
-            commentLevel,
-            parent || comment
-          )
+          return Handlebars.helpers.commentTag(tag, parent || comment)
         })
         md.push(tags.join("\n\n"))
       }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/decrement-current-title-level.ts

@@ -0,0 +1,9 @@
+import { MarkdownTheme } from "../../theme"
+import * as Handlebars from "handlebars"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper("decrementCurrentTitleLevel", function () {
+    const { currentTitleLevel } = theme
+    theme.setCurrentTitleLevel(currentTitleLevel - 1)
+  })
+}

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

@@ -2,18 +2,15 @@ import * as Handlebars from "handlebars"
 import { Reflection } from "typedoc"
 
 export default function () {
-  Handlebars.registerHelper(
-    "example",
-    function (reflection: Reflection, commentLevel = 4) {
-      const exampleTag = reflection.comment?.blockTags.find(
-        (tag) => tag.tag === "@example"
-      )
+  Handlebars.registerHelper("example", function (reflection: Reflection) {
+    const exampleTag = reflection.comment?.blockTags.find(
+      (tag) => tag.tag === "@example"
+    )
 
-      if (!exampleTag) {
-        return ""
-      }
-
-      return Handlebars.helpers.commentTag(exampleTag, commentLevel, reflection)
+    if (!exampleTag) {
+      return ""
     }
-  )
+
+    return Handlebars.helpers.commentTag(exampleTag, reflection)
+  })
 }

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/has-more-than-one-signature.ts

@@ -0,0 +1,11 @@
+import { DeclarationReflection } from "typedoc"
+import * as Handlebars from "handlebars"
+
+export default function () {
+  Handlebars.registerHelper(
+    "hasMoreThanOneSignature",
+    function (model: DeclarationReflection) {
+      return (model.signatures?.length || 0) > 1
+    }
+  )
+}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/if-can-show-constructors-title.ts

@@ -0,0 +1,14 @@
+import * as Handlebars from "handlebars"
+import { ReflectionGroup } from "typedoc"
+
+export default function () {
+  Handlebars.registerHelper(
+    "ifCanShowConstructorTitle",
+    function (this: ReflectionGroup, options: Handlebars.HelperOptions) {
+      return this.title.toLowerCase() !== "constructors" ||
+        this.children.length > 1
+        ? options.fn(this)
+        : options.inverse(this)
+    }
+  )
+}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/increment-current-title-level.ts

@@ -0,0 +1,9 @@
+import { MarkdownTheme } from "../../theme"
+import * as Handlebars from "handlebars"
+
+export default function (theme: MarkdownTheme) {
+  Handlebars.registerHelper("incrementCurrentTitleLevel", function () {
+    const { currentTitleLevel } = theme
+    theme.setCurrentTitleLevel(currentTitleLevel + 1)
+  })
+}

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

@@ -10,6 +10,10 @@ export default function (theme: MarkdownTheme) {
     function (this: PageEvent<any>, shouldEscape = true) {
       const { reflectionTitle } = theme.getFormattingOptionsForLocation()
 
+      if (reflectionTitle?.fullReplacement?.length) {
+        return reflectionTitle.fullReplacement
+      }
+
       const title: string[] = [""]
       if (
         reflectionTitle?.kind &&

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

@@ -13,11 +13,15 @@ export default function (theme: MarkdownTheme) {
     function (this: SignatureReflection, accessor?: string, standalone = true) {
       const { sections, expandMembers = false } =
         theme.getFormattingOptionsForLocation()
-      if (sections && sections.member_signature_title === false) {
+      const parentHasMoreThanOneSignature =
+        Handlebars.helpers.hasMoreThanOneSignature(this.parent)
+      if (
+        sections &&
+        sections.member_signature_title === false &&
+        !parentHasMoreThanOneSignature
+      ) {
         // only show title if there are more than one signatures
-        if (!this.parent.signatures || this.parent.signatures.length <= 1) {
-          return ""
-        }
+        return ""
       }
       const md: string[] = []
 
@@ -36,12 +40,12 @@ export default function (theme: MarkdownTheme) {
       if (accessor) {
         md.push(
           `${accessor}${
-            expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"
+            expandMembers ? `${Handlebars.helpers.titleLevel()} ` : "**"
           }${this.name}${!expandMembers ? "**" : ""}`
         )
       } else if (this.name !== "__call" && this.name !== "__type") {
         md.push(
-          `${expandMembers ? `${Handlebars.helpers.titleLevel(4)} ` : "**"}${
+          `${expandMembers ? `${Handlebars.helpers.titleLevel()} ` : "**"}${
             this.name
           }${!expandMembers ? "**" : ""}`
         )

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

@@ -1,44 +1,18 @@
 import { MarkdownTheme } from "../../theme"
 import * as Handlebars from "handlebars"
-import { SignatureReflection, Reflection } from "typedoc"
+import { Reflection } from "typedoc"
 
 export default function (theme: MarkdownTheme) {
-  Handlebars.registerHelper(
-    "titleLevel",
-    function (this: Reflection, originalLevel = 3): string {
-      const { expandMembers, sections } =
-        theme.getFormattingOptionsForLocation()
+  Handlebars.registerHelper("titleLevel", function (this: Reflection): string {
+    const { currentTitleLevel } = theme
 
-      if (!expandMembers) {
-        return Array(originalLevel).fill("#").join("")
-      }
+    // let titleLevel = currentTitleLevel
 
-      const { allReflectionsHaveOwnDocument } = theme
+    // if (isChild) {
+    //   titleLevel++
+    //   theme.setCurrentTitleLevel(titleLevel + 1)
+    // }
 
-      let isSignatureChild = false
-      if (
-        sections &&
-        sections.member_signature_title === false &&
-        (this instanceof SignatureReflection || this.variant === "signature")
-      ) {
-        // only show title if there are more than one signatures
-        isSignatureChild =
-          this.parent !== undefined &&
-          "signatures" in this.parent &&
-          (this.parent.signatures as SignatureReflection[]).length > 1
-      }
-
-      const numberToSubtract = allReflectionsHaveOwnDocument
-        ? isSignatureChild
-          ? 1
-          : 2
-        : isSignatureChild
-        ? 0
-        : 1
-
-      const level = originalLevel - numberToSubtract
-
-      return Array(level).fill("#").join("")
-    }
-  )
+    return Array(currentTitleLevel).fill("#").join("")
+  })
 }

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

@@ -4,7 +4,7 @@
 
 {{#if hasVisibleComponent}}
 
-{{{comments this true true 4 model}}}
+{{{comments this true true model}}}
 
 {{/if}}
 

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

@@ -12,7 +12,7 @@
 
 {{#if (sectionEnabled "member_declaration_example")}}
 
-{{{example this 4}}}
+{{{example this}}}
 
 {{/if}}
 
@@ -20,7 +20,7 @@
 
 {{#if typeParameters}}
 
-{{{titleLevel 4}}} Type Parameters
+{{{titleLevel}}} Type Parameters
 
 {{#with typeParameters}}
 
@@ -40,7 +40,7 @@
 
 {{#with type.declaration.indexSignature}}
 
-{{titleLevel 4}} Index signature
+{{titleLevel}} Index signature
 
 {{{indexSignatureTitle}}}
 
@@ -58,17 +58,21 @@
 
 {{#if type.declaration.children}}
 
-{{{titleLevel 4}}} Call signature
+{{{titleLevel}}} Call signature
 
 {{else}}
 
-{{{titleLevel 4}}} Type declaration
+{{{titleLevel}}} Type declaration
 
 {{/if}}
 
 {{#each type.declaration.signatures}}
 
-{{> member.signature showSources=false commentLevel=5 }}
+{{incrementCurrentTitleLevel}}
+
+{{> member.signature showSources=false }}
+
+{{decrementCurrentTitleLevel}}
 
 {{/each}}
 
@@ -82,7 +86,7 @@
 
 {{#with type.declaration}}
 
-{{{titleLevel 4}}} Type declaration
+{{{titleLevel}}} Type declaration
 
 {{/with}}
 

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

@@ -4,7 +4,7 @@
 
 {{#with getSignature}}
 
-{{> member.signature accessor="get" showSources=true commentLevel=4 }}
+{{> member.signature accessor="get" showSources=true }}
 
 {{/with}}
 
@@ -18,7 +18,7 @@
 
 {{#with setSignature}}
 
-{{> member.signature accessor="set" showSources=true commentLevel=4 }}
+{{> member.signature accessor="set" showSources=true }}
 
 {{/with}}
 

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

@@ -2,7 +2,9 @@
 
 {{#if name}}
 
-{{titleLevel 4}} {{#ifNamedAnchors}}<a id="{{anchor}}" name="{{this.anchor}}"></a> {{/ifNamedAnchors}}{{ escape name }}
+{{titleLevel}} {{#ifNamedAnchors}}<a id="{{anchor}}" name="{{this.anchor}}"></a> {{/ifNamedAnchors}}{{ escape name }}
+
+{{incrementCurrentTitleLevel}}
 
 {{/if}}
 
@@ -14,7 +16,7 @@
 
 {{#each signatures}}
 
-{{> member.signature showSources=true commentLevel=../commentLevel }}
+{{> member.signature showSources=true }}
 
 {{/each}}
 
@@ -59,3 +61,13 @@
 ___
 {{/unless}}
 {{/unless}}
+
+{{#unless hasOwnDocument}}
+
+{{#if name}}
+
+{{decrementCurrentTitleLevel}}
+
+{{/if}}
+
+{{/unless}}

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

@@ -1,5 +1,15 @@
 {{{signatureTitle accessor}}}
 
+{{#if (getFormattingOption "expandMembers")}}
+
+{{#if (hasMoreThanOneSignature parent)}}
+
+{{incrementCurrentTitleLevel}}
+
+{{/if}}
+
+{{/if}}
+
 {{#if (sectionEnabled "member_signature_comment")}}
 
 {{#with comment}}
@@ -16,7 +26,7 @@
 
 {{#if (sectionEnabled "member_signature_example")}}
 
-{{{example this commentLevel}}}
+{{{example this}}}
 
 {{/if}}
 
@@ -24,7 +34,7 @@
 
 {{#if typeParameters}}
 
-{{{titleLevel commentLevel}}} Type Parameters
+{{{titleLevel}}} Type Parameters
 
 {{#with typeParameters}}
 
@@ -40,7 +50,7 @@
 
 {{#if parameters}}
 
-{{{titleLevel commentLevel}}} Parameters
+{{{titleLevel}}} Parameters
 
 {{#with parameters}}
 
@@ -56,7 +66,7 @@
 
 {{#if type}}
 
-{{{titleLevel commentLevel}}} Returns
+{{{titleLevel}}} Returns
 
 {{#if (sectionEnabled "member_signature_returns")}}
 
@@ -76,12 +86,16 @@
 
 {{#if declaration.signatures}}
 
+{{incrementCurrentTitleLevel}}
+
 {{#each declaration.signatures}}
 
-{{> member.signature showSources=false commentLevel=commentLevel }}
+{{> member.signature showSources=false }}
 
 {{/each}}
 
+{{decrementCurrentTitleLevel}}
+
 {{/if}}
 
 {{/if}}
@@ -112,7 +126,7 @@
 
 {{#if hasVisibleComponent}}
 
-{{{comments this false true commentLevel ..}}}
+{{{comments this false true ..}}}
 
 {{/if}}
 
@@ -124,8 +138,22 @@
 
 {{#if showSources}}
 
+{{incrementCurrentTitleLevel}}
+
 {{> member.sources}}
 
+{{decrementCurrentTitleLevel}}
+
+{{/if}}
+
+{{/if}}
+
+{{#if (getFormattingOption "expandMembers")}}
+
+{{#if (hasMoreThanOneSignature parent)}}
+
+{{decrementCurrentTitleLevel}}
+
 {{/if}}
 
 {{/if}}

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

@@ -2,7 +2,7 @@
 
 {{#if implementationOf}}
 
-{{titleLevel 4}} Implementation of
+{{titleLevel}} Implementation of
 
 {{#with implementationOf}}
 
@@ -18,7 +18,7 @@
 
 {{#if inheritedFrom}}
 
-{{titleLevel 4}} Inherited from
+{{titleLevel}} Inherited from
 
 {{#with inheritedFrom}}
 
@@ -34,7 +34,7 @@
 
 {{#if overwrites}}
 
-{{titleLevel 4}} Overrides
+{{titleLevel}} Overrides
 
 {{#with overwrites}}
 
@@ -50,7 +50,7 @@
 
 {{#if sources}}
 
-{{titleLevel 4}} Defined in
+{{titleLevel}} Defined in
 
 {{#each sources}}
 

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

@@ -10,7 +10,13 @@ ___
 
 {{#unless (getFormattingOption "expandMembers")}}
 
-## {{title}} {{../title}}
+{{#ifCanShowConstructorTitle}}
+
+{{titleLevel}} {{title}} {{../title}}
+
+{{incrementCurrentTitleLevel}}
+
+{{/ifCanShowConstructorTitle}}
 
 {{/unless}}
 
@@ -26,19 +32,35 @@ ___
 
 {{#each children}}
 
-{{> member commentLevel=5}}
+{{> member }}
 
 {{/each}}
 
 {{/if}}
 
+{{#unless (getFormattingOption "expandMembers")}}
+
+{{#ifCanShowConstructorTitle}}
+
+{{decrementCurrentTitleLevel}}
+
+{{/ifCanShowConstructorTitle}}
+
+{{/unless}}
+
 {{/each}}
 
 {{else}}
 
 {{#unless (getFormattingOption "expandMembers")}}
 
-## {{title}}
+{{#ifCanShowConstructorTitle}}
+
+{{titleLevel}} {{title}}
+
+{{incrementCurrentTitleLevel}}
+
+{{/ifCanShowConstructorTitle}}
 
 {{/unless}}
 
@@ -54,12 +76,22 @@ ___
 
 {{#each children}}
 
-{{> member commentLevel=5}}
+{{> member}}
 
 {{/each}}
 
 {{/if}}
 
+{{#unless (getFormattingOption "expandMembers")}}
+
+{{#ifCanShowConstructorTitle}}
+
+{{decrementCurrentTitleLevel}}
+
+{{/ifCanShowConstructorTitle}}
+
+{{/unless}}
+
 {{/if}}
 
 {{/if}}

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

@@ -8,7 +8,9 @@
 
 {{#unless (getFormattingOption "expandMembers")}}
 
-## {{title}}
+{{{titleLevel}}} {{title}}
+
+{{incrementCurrentTitleLevel}}
 
 {{/unless}}
 
@@ -16,12 +18,18 @@
 
 {{#unless hasOwnDocument}}
 
-{{> member commentLevel=4}}
+{{> member}}
 
 {{/unless}}
 
 {{/each}}
 
+{{#unless (getFormattingOption "expandMembers")}}
+
+{{decrementCurrentTitleLevel}}
+
+{{/unless}}
+
 {{/unless}}
 
 {{/each}}
@@ -32,6 +40,10 @@
 
 {{#unless allChildrenHaveOwnDocument}}
 
+{{#unless @first}}
+___
+{{/unless}}
+
 {{> members.group}}
 
 {{/unless}}

docs-util/packages/typedoc-plugin-markdown-medusa/src/resources/partials/section-title.hbs

@@ -1,9 +1,13 @@
 {{#if showSources}}
 
-{{{titleLevel 4}}} {{{title}}}
+{{incrementCurrentTitleLevel}}
 
-{{else}}
+{{/if}}
 
-{{{titleLevel 5}}} {{{title}}}
+{{{titleLevel}}} {{{title}}}
+
+{{#if showSources}}
+
+{{decrementCurrentTitleLevel}}
 
 {{/if}}

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

@@ -1,6 +1,6 @@
 {{#ifShowPageTitle}}
 
-# {{{reflectionTitle true}}}
+{{titleLevel}} {{{reflectionTitle true}}}
 
 {{/ifShowPageTitle}}
 

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

@@ -1,5 +1,7 @@
 {{> header}}
 
+{{incrementCurrentTitleLevel}}
+
 {{#with model.readme}}
 
 {{{comment this}}}

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

@@ -2,6 +2,8 @@
 
 {{> title}}
 
+{{incrementCurrentTitleLevel}}
+
 {{#with model}}
 
 {{#if (sectionEnabled "reflection_comment")}}
@@ -18,7 +20,7 @@
 
 {{#if (sectionEnabled "reflection_example")}}
 
-{{{example model 2}}}
+{{{example model}}}
 
 {{/if}}
 
@@ -26,7 +28,7 @@
 
 {{#if model.typeParameters}}
 
-## Type parameters
+{{{titleLevel}}} Type parameters
 
 {{#with model.typeParameters}}
 
@@ -42,7 +44,7 @@
 
 {{#ifShowTypeHierarchy}}
 
-## Hierarchy
+{{{titleLevel}}} Hierarchy
 
 {{#with model.typeHierarchy}}
 
@@ -58,7 +60,7 @@
 
 {{#if model.implementedTypes}}
 
-## Implements
+{{{titleLevel}}} Implements
 
 {{#each model.implementedTypes}}
 - {{{type}}}
@@ -72,7 +74,7 @@
 
 {{#if model.implementedBy}}
 
-## Implemented by
+{{{titleLevel}}} Implemented by
 
 {{#each model.implementedBy}}
 - {{{type}}}
@@ -86,18 +88,26 @@
 
 {{#if model.signatures}}
 
-## Callable
+{{{titleLevel}}} Callable
 
 {{#with model}}
 
+{{incrementCurrentTitleLevel}}
+
 {{#each signatures}}
 
-### {{name}}
+{{{titleLevel}}} {{name}}
 
-{{> member.signature showSources=true commentLevel=4 }}
+{{incrementCurrentTitleLevel}}
+
+{{> member.signature showSources=true }}
+
+{{decrementCurrentTitleLevel}}
 
 {{/each}}
 
+{{decrementCurrentTitleLevel}}
+
 {{/with}}
 
 {{/if}}
@@ -108,16 +118,20 @@
 
 {{#if model.indexSignature}}
 
-## Indexable
+{{{titleLevel}}} Indexable
 
 {{#with model}}
 
 {{#with indexSignature}}
 
+{{incrementCurrentTitleLevel}}
+
 {{{indexSignatureTitle}}}
 
 {{> comment}}
 
+{{decrementCurrentTitleLevel}}
+
 {{/with}}
 
 {{/with}}

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

@@ -4,6 +4,10 @@
 
 {{#with model}}
 
-{{> member showSources=false commentLevel=4}}
+{{incrementCurrentTitleLevel}}
+
+{{> member showSources=false}}
+
+{{decrementCurrentTitleLevel}}
 
 {{/with}}

docs-util/packages/typedoc-plugin-markdown-medusa/src/theme.ts

@@ -54,6 +54,7 @@ export class MarkdownTheme extends Theme {
   reflection?: DeclarationReflection
   location!: string
   anchorMap: Record<string, string[]> = {}
+  currentTitleLevel = 1
 
   static URL_PREFIX = /^(http|ftp)s?:\/\//
 
@@ -355,6 +356,8 @@ export class MarkdownTheme extends Theme {
    * @param page  An event object describing the current render operation.
    */
   protected onBeginPage(page: PageEvent) {
+    // reset header level counter
+    this.currentTitleLevel = 1
     this.location = page.url
     this.reflection =
       page.model instanceof DeclarationReflection ? page.model : undefined
@@ -403,6 +406,10 @@ export class MarkdownTheme extends Theme {
     return `modules.${this.mdxOutput ? "mdx" : "md"}`
   }
 
+  setCurrentTitleLevel(value: number) {
+    this.currentTitleLevel = value
+  }
+
   getFormattingOptionsForLocation(): FormattingOptionType {
     if (!this.location) {
       return {}

docs-util/packages/typedoc-plugin-markdown-medusa/src/types.ts

@@ -67,6 +67,7 @@ export type FormattingOptionType = {
     kind: boolean
     typeParameters: boolean
     suffix?: string
+    fullReplacement?: string
   }
   reflectionDescription?: string
   expandMembers?: boolean

docs-util/packages/typedoc-plugin-markdown-medusa/src/utils/reflection-formatter.ts

@@ -109,7 +109,7 @@ export function reflectionComponentFormatter(
       ? getType(reflection.type, "object")
       : getReflectionType(reflection, "object", true),
     description: comments
-      ? stripLineBreaks(Handlebars.helpers.comments(comments, true, false))
+      ? Handlebars.helpers.comments(comments, true, false)
       : "",
     optional,
     defaultValue,
@@ -230,8 +230,8 @@ export function getDefaultValue(
     parameter.defaultValue !== "..."
     ? `${parameter.defaultValue}`
     : defaultComment
-    ? defaultComment.content.map((content) => stripCode(content.text)).join()
-    : null
+      ? defaultComment.content.map((content) => stripCode(content.text)).join()
+      : null
 }
 
 export function hasDefaultValues(parameters: ReflectionParameterType[]) {

docs-util/packages/utils/package.json

@@ -18,7 +18,7 @@
   },
   "devDependencies": {
     "@types/node": "^16.11.10",
-    "typescript": "^4.6"
+    "typescript": "5.2"
   },
   "dependencies": {
     "rimraf": "^5.0.5"

docs-util/packages/workflows-diagrams-generator/package.json

@@ -21,7 +21,7 @@
     "@mermaid-js/mermaid-cli": "^10.6.1",
     "commander": "^11.1.0",
     "ts-node": "^10.9.1",
-    "typescript": "^5.1.6"
+    "typescript": "5.2"
   },
   "devDependencies": {
     "@types/node": "^20.9.4"

docs-util/packages/workflows-diagrams-generator/src/commands/generate.ts

@@ -4,6 +4,7 @@ import * as path from "path"
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs"
 import registerWorkflows from "../utils/register-workflows.js"
 import DiagramBuilder from "../classes/diagram-builder.js"
+// @ts-expect-error mermaid typing issue
 import { run as runMermaid } from "@mermaid-js/mermaid-cli"
 
 type Options = {

docs-util/yarn.lock

@@ -3730,7 +3730,7 @@ __metadata:
     typedoc-plugin-missing-exports: ^2.1.0
     typedoc-plugin-reference-excluder: 1.1.3
     typedoc-plugin-rename-defaults: ^0.6.6
-    typescript: ^5.2.2
+    typescript: 5.2
   languageName: unknown
   linkType: soft
 
@@ -4232,7 +4232,7 @@ __metadata:
     eslint: ^8.53.0
     glob: ^10.3.10
     typedoc-plugin-markdown: ^3.16.0
-    typescript: ^4.6
+    typescript: 5.2
     utils: "*"
     yaml: ^2.3.3
   peerDependencies:
@@ -4256,7 +4256,7 @@ __metadata:
     "@types/node": ^16.11.10
     copyfiles: ^2.4.1
     handlebars: ^4.7.8
-    typescript: ^4.6
+    typescript: 5.2
     utils: "*"
   peerDependencies:
     typedoc: 0.25.x
@@ -4337,43 +4337,23 @@ __metadata:
   languageName: node
   linkType: hard
 
-"typescript@npm:^4.6":
-  version: 4.9.5
-  resolution: "typescript@npm:4.9.5"
+"typescript@npm:5.2":
+  version: 5.2.2
+  resolution: "typescript@npm:5.2.2"
   bin:
     tsc: bin/tsc
     tsserver: bin/tsserver
-  checksum: 5f6cad2e728a8a063521328e612d7876e12f0d8a8390d3b3aaa452a6a65e24e9ac8ea22beb72a924fd96ea0a49ea63bb4e251fb922b12eedfb7f7a26475e5c56
+  checksum: 91ae3e6193d0ddb8656d4c418a033f0f75dec5e077ebbc2bd6d76439b93f35683936ee1bdc0e9cf94ec76863aa49f27159b5788219b50e1cd0cd6d110aa34b07
   languageName: node
   linkType: hard
 
-"typescript@npm:^5.1.6, typescript@npm:^5.2.2":
-  version: 5.3.2
-  resolution: "typescript@npm:5.3.2"
+"typescript@patch:typescript@5.2#~builtin<compat/typescript>":
+  version: 5.2.2
+  resolution: "typescript@patch:typescript@npm%3A5.2.2#~builtin<compat/typescript>::version=5.2.2&hash=7ad353"
   bin:
     tsc: bin/tsc
     tsserver: bin/tsserver
-  checksum: d7dbe1fbe19039e36a65468ea64b5d338c976550394ba576b7af9c68ed40c0bc5d12ecce390e4b94b287a09a71bd3229f19c2d5680611f35b7c53a3898791159
-  languageName: node
-  linkType: hard
-
-"typescript@patch:typescript@^4.6#~builtin<compat/typescript>":
-  version: 4.9.5
-  resolution: "typescript@patch:typescript@npm%3A4.9.5#~builtin<compat/typescript>::version=4.9.5&hash=7ad353"
-  bin:
-    tsc: bin/tsc
-    tsserver: bin/tsserver
-  checksum: 897c8ac656e01b132fa82be6a8e34c4507b19be63dbf1ff1d8287d775519081a7c91dd0ca3ec62536c8137228141d65b238dfb2e8987a3f5182818f58f83e7d7
-  languageName: node
-  linkType: hard
-
-"typescript@patch:typescript@^5.1.6#~builtin<compat/typescript>, typescript@patch:typescript@^5.2.2#~builtin<compat/typescript>":
-  version: 5.3.2
-  resolution: "typescript@patch:typescript@npm%3A5.3.2#~builtin<compat/typescript>::version=5.3.2&hash=7ad353"
-  bin:
-    tsc: bin/tsc
-    tsserver: bin/tsserver
-  checksum: c81b9bd20c6dbe90fa43e876c586021447f2b47baede9fa542b1f56715835c043e23b2eaf19c42c067cc6f5ae512bd9a9be28a67b3a1d9807f8c9cfb1269875e
+  checksum: 303979762f9b8932c53f8149e866521a1265168b5c0fde8cc8ad83ac3d0e8ede8096cb02dff5f2de048e7f118a6f61902f81da12d5972c7fb582f09f2f18d169
   languageName: node
   linkType: hard
 
@@ -4499,7 +4479,7 @@ __metadata:
   dependencies:
     "@types/node": ^16.11.10
     rimraf: ^5.0.5
-    typescript: ^4.6
+    typescript: 5.2
   peerDependencies:
     typedoc: 0.25.x
   languageName: unknown
@@ -4586,7 +4566,7 @@ __metadata:
     "@types/node": ^20.9.4
     commander: ^11.1.0
     ts-node: ^10.9.1
-    typescript: ^5.1.6
+    typescript: 5.2
   bin:
     workflow-diagrams-generator: dist/index.js
   languageName: unknown