From 8830a249155e981755df289c92f6eadea77a7f26 Mon Sep 17 00:00:00 2001
From: tgreyuk <tgreyuk@gmail.com>
Date: Tue, 2 Jul 2024 19:56:27 +0100
Subject: [PATCH] feat(core): configure ordering of block tags and support
 TypeDoc relative links implementation

---
 .changeset/old-impalas-cross.md               |   5 +
 .changeset/swift-baboons-bathe.md             |   2 +-
 .changeset/unlucky-parents-vanish.md          |   5 +
 .changeset/violet-mails-design.md             |   2 +-
 .../index/interfaces/PluginOptions.md         | 146 +++++++------
 .../documents/Getting-Started.md              |  17 +-
 .../libs/namespaces/utils/README.md           |  21 --
 .../options/namespaces/declarations/README.md |  73 +++++--
 .../types/interfaces/PluginOptions.md         |  77 ++++---
 .../prebuild-options/tasks/generate-docs.ts   |  18 +-
 .../prebuild-options/tasks/generate-models.ts |  24 +--
 .../api-docs/Interface.PluginOptions.mdx      |   8 +
 docs/pages/docs/_meta.js                      |   4 +-
 ...igration-guide.mdx => migration-guide.mdx} |   2 +-
 docs/pages/docs/options.mdx                   |   1 +
 docs/pages/docs/options/display-options.mdx   |  24 ++-
 docs/public/schema.json                       |  12 ++
 .../typedoc-plugin-markdown/src/_typedoc.d.ts |   1 +
 .../src/options/declarations.ts               |  29 ++-
 .../src/renderer/overrides.ts                 |  21 ++
 .../context/helpers/get-comment-parts.ts      |  21 ++
 .../context/partials/comments.comment.ts      |  17 +-
 .../context/partials/member.declaration.ts    |  35 +--
 .../context/partials/member.signature.ts      |   2 +
 .../src/types/options.ts                      |   5 +
 .../internal/getting-started.md               |  16 +-
 .../test/fixtures/config.ts                   |   3 +
 .../test/fixtures/src/comments/index.ts       |  49 ++++-
 .../specs/__snapshots__/comments.spec.ts.snap | 200 ++++++++++++++++--
 .../reflection.function.spec.ts.snap          |  16 +-
 .../specs/__snapshots__/urls.spec.ts.snap     |  58 +++++
 .../test/specs/comments.spec.ts               |  14 ++
 .../test/specs/urls.spec.ts                   |   4 +
 .../test/specs/utils.spec.ts                  |   2 +-
 packages/typedoc-vitepress-theme/CHANGELOG.md |   2 +-
 35 files changed, 702 insertions(+), 234 deletions(-)
 create mode 100644 .changeset/old-impalas-cross.md
 create mode 100644 .changeset/unlucky-parents-vanish.md
 rename docs/pages/docs/{v4-migration-guide.mdx => migration-guide.mdx} (99%)

diff --git a/.changeset/old-impalas-cross.md b/.changeset/old-impalas-cross.md
new file mode 100644
index 00000000..3a269f15
--- /dev/null
+++ b/.changeset/old-impalas-cross.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Exposed "blockTagsPreserveOrder" option to configure ordering of comment block tags (#627).
diff --git a/.changeset/swift-baboons-bathe.md b/.changeset/swift-baboons-bathe.md
index 1b5caf63..4354e7f1 100644
--- a/.changeset/swift-baboons-bathe.md
+++ b/.changeset/swift-baboons-bathe.md
@@ -2,4 +2,4 @@
 'typedoc-plugin-markdown': patch
 ---
 
-- Exposed "useHTMLEncodedBrackets" option (#564).
+- Exposed "useHTMLEncodedBrackets" option for alternative angle bracket escaping(#564).
diff --git a/.changeset/unlucky-parents-vanish.md b/.changeset/unlucky-parents-vanish.md
new file mode 100644
index 00000000..8e5ce8f3
--- /dev/null
+++ b/.changeset/unlucky-parents-vanish.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Support TypeDoc 0.26 relative links implementation (#645).
diff --git a/.changeset/violet-mails-design.md b/.changeset/violet-mails-design.md
index 6387a2f7..540439e9 100644
--- a/.changeset/violet-mails-design.md
+++ b/.changeset/violet-mails-design.md
@@ -2,4 +2,4 @@
 'typedoc-plugin-markdown': patch
 ---
 
-- Allow htmlTable format key for indexes (#618)
+- Allow "htmlTable" format key for indexes (#618).
diff --git a/devguide/docusaurus-plugin-typedoc/index/interfaces/PluginOptions.md b/devguide/docusaurus-plugin-typedoc/index/interfaces/PluginOptions.md
index 5b34f694..f96e3153 100644
--- a/devguide/docusaurus-plugin-typedoc/index/interfaces/PluginOptions.md
+++ b/devguide/docusaurus-plugin-typedoc/index/interfaces/PluginOptions.md
@@ -13,62 +13,64 @@ Describes the options declared by the plugin.
     * [Inherited from](#inherited-from)
   * [anchorPrefix](#anchorprefix)
     * [Inherited from](#inherited-from-1)
-  * [classPropertiesFormat](#classpropertiesformat)
+  * [blockTagsPreserveOrder](#blocktagspreserveorder)
     * [Inherited from](#inherited-from-2)
-  * [entryFileName](#entryfilename)
+  * [classPropertiesFormat](#classpropertiesformat)
     * [Inherited from](#inherited-from-3)
-  * [entryModule](#entrymodule)
+  * [entryFileName](#entryfilename)
     * [Inherited from](#inherited-from-4)
-  * [enumMembersFormat](#enummembersformat)
+  * [entryModule](#entrymodule)
     * [Inherited from](#inherited-from-5)
+  * [enumMembersFormat](#enummembersformat)
+    * [Inherited from](#inherited-from-6)
   * [~~excludeGroups~~](#excludegroups)
     * [Deprecated](#deprecated)
-    * [Inherited from](#inherited-from-6)
-  * [excludeScopesInPaths](#excludescopesinpaths)
     * [Inherited from](#inherited-from-7)
-  * [expandObjects](#expandobjects)
+  * [excludeScopesInPaths](#excludescopesinpaths)
     * [Inherited from](#inherited-from-8)
-  * [expandParameters](#expandparameters)
+  * [expandObjects](#expandobjects)
     * [Inherited from](#inherited-from-9)
-  * [fileExtension](#fileextension)
+  * [expandParameters](#expandparameters)
     * [Inherited from](#inherited-from-10)
-  * [flattenOutputFiles](#flattenoutputfiles)
+  * [fileExtension](#fileextension)
     * [Inherited from](#inherited-from-11)
-  * [hideBreadcrumbs](#hidebreadcrumbs)
+  * [flattenOutputFiles](#flattenoutputfiles)
     * [Inherited from](#inherited-from-12)
-  * [hideGroupHeadings](#hidegroupheadings)
+  * [hideBreadcrumbs](#hidebreadcrumbs)
     * [Inherited from](#inherited-from-13)
-  * [hidePageHeader](#hidepageheader)
+  * [hideGroupHeadings](#hidegroupheadings)
     * [Inherited from](#inherited-from-14)
-  * [hidePageTitle](#hidepagetitle)
+  * [hidePageHeader](#hidepageheader)
     * [Inherited from](#inherited-from-15)
-  * [indexFormat](#indexformat)
+  * [hidePageTitle](#hidepagetitle)
     * [Inherited from](#inherited-from-16)
-  * [interfacePropertiesFormat](#interfacepropertiesformat)
+  * [indexFormat](#indexformat)
     * [Inherited from](#inherited-from-17)
-  * [membersWithOwnFile](#memberswithownfile)
+  * [interfacePropertiesFormat](#interfacepropertiesformat)
     * [Inherited from](#inherited-from-18)
-  * [mergeReadme](#mergereadme)
+  * [membersWithOwnFile](#memberswithownfile)
     * [Inherited from](#inherited-from-19)
+  * [mergeReadme](#mergereadme)
+    * [Inherited from](#inherited-from-20)
   * [navigationModel](#navigationmodel)
     * [excludeGroups](#excludegroups-1)
     * [excludeCategories](#excludecategories)
     * [excludeFolders](#excludefolders)
-    * [Inherited from](#inherited-from-20)
-  * [outputFileStrategy](#outputfilestrategy)
     * [Inherited from](#inherited-from-21)
-  * [parametersFormat](#parametersformat)
+  * [outputFileStrategy](#outputfilestrategy)
     * [Inherited from](#inherited-from-22)
-  * [preserveAnchorCasing](#preserveanchorcasing)
+  * [parametersFormat](#parametersformat)
     * [Inherited from](#inherited-from-23)
-  * [propertiesFormat](#propertiesformat)
+  * [preserveAnchorCasing](#preserveanchorcasing)
     * [Inherited from](#inherited-from-24)
-  * [propertyMembersFormat](#propertymembersformat)
+  * [propertiesFormat](#propertiesformat)
     * [Inherited from](#inherited-from-25)
-  * [publicPath](#publicpath)
+  * [propertyMembersFormat](#propertymembersformat)
     * [Inherited from](#inherited-from-26)
-  * [sanitizeComments](#sanitizecomments)
+  * [publicPath](#publicpath)
     * [Inherited from](#inherited-from-27)
+  * [sanitizeComments](#sanitizecomments)
+    * [Inherited from](#inherited-from-28)
   * [tableColumnSettings](#tablecolumnsettings)
     * [hideDefaults](#hidedefaults)
     * [hideInherited](#hideinherited)
@@ -77,7 +79,7 @@ Describes the options declared by the plugin.
     * [hideSources](#hidesources)
     * [hideValues](#hidevalues)
     * [leftAlignHeaders](#leftalignheaders)
-    * [Inherited from](#inherited-from-28)
+    * [Inherited from](#inherited-from-29)
   * [textContentMappings](#textcontentmappings)
     * [header.title](#headertitle)
     * [header.docs](#headerdocs)
@@ -85,15 +87,15 @@ Describes the options declared by the plugin.
     * [title.indexPage](#titleindexpage)
     * [title.memberPage](#titlememberpage)
     * [footer.text](#footertext)
-    * [Inherited from](#inherited-from-29)
-  * [typeDeclarationFormat](#typedeclarationformat)
     * [Inherited from](#inherited-from-30)
-  * [useCodeBlocks](#usecodeblocks)
+  * [typeDeclarationFormat](#typedeclarationformat)
     * [Inherited from](#inherited-from-31)
-  * [useHTMLAnchors](#usehtmlanchors)
+  * [useCodeBlocks](#usecodeblocks)
     * [Inherited from](#inherited-from-32)
-  * [useHTMLEncodedBrackets](#usehtmlencodedbrackets)
+  * [useHTMLAnchors](#usehtmlanchors)
     * [Inherited from](#inherited-from-33)
+  * [useHTMLEncodedBrackets](#usehtmlencodedbrackets)
+    * [Inherited from](#inherited-from-34)
 
 ## Extends
 
@@ -143,6 +145,22 @@ typedoc-plugin-markdown/dist/types/options.d.ts:8
 
 ***
 
+### blockTagsPreserveOrder
+
+> **blockTagsPreserveOrder**: `string`\[]
+
+Specifies comment block tags that should preserve their position in relation to the comment summary.
+
+#### Inherited from
+
+[`PluginOptions`](../../../typedoc-plugin-markdown/types/interfaces/PluginOptions.md).[`blockTagsPreserveOrder`](../../../typedoc-plugin-markdown/types/interfaces/PluginOptions.md#blocktagspreserveorder)
+
+#### Defined in
+
+typedoc-plugin-markdown/dist/types/options.d.ts:12
+
+***
+
 ### classPropertiesFormat
 
 > **classPropertiesFormat**: `"table"` | `"list"` | `"htmlTable"`
@@ -155,7 +173,7 @@ Sets the format of property groups for classes.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:12
+typedoc-plugin-markdown/dist/types/options.d.ts:16
 
 ***
 
@@ -171,7 +189,7 @@ The file name of the entry page.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:16
+typedoc-plugin-markdown/dist/types/options.d.ts:20
 
 ***
 
@@ -187,7 +205,7 @@ The name of a module that should act as the root page for the documentation.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:20
+typedoc-plugin-markdown/dist/types/options.d.ts:24
 
 ***
 
@@ -203,7 +221,7 @@ Sets the format of enumeration members.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:24
+typedoc-plugin-markdown/dist/types/options.d.ts:28
 
 ***
 
@@ -221,7 +239,7 @@ This option has been renamed hideGroupHeadings to better reflect its purpose.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:28
+typedoc-plugin-markdown/dist/types/options.d.ts:32
 
 ***
 
@@ -237,7 +255,7 @@ Exclude writing @ scope directories in paths.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:32
+typedoc-plugin-markdown/dist/types/options.d.ts:36
 
 ***
 
@@ -253,7 +271,7 @@ Expand objects inside declarations.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:36
+typedoc-plugin-markdown/dist/types/options.d.ts:40
 
 ***
 
@@ -269,7 +287,7 @@ Expand parameters in signature parentheses to display type information.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:40
+typedoc-plugin-markdown/dist/types/options.d.ts:44
 
 ***
 
@@ -285,7 +303,7 @@ Specify the file extension for generated output files.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:44
+typedoc-plugin-markdown/dist/types/options.d.ts:48
 
 ***
 
@@ -301,7 +319,7 @@ Flatten output files to a single directory.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:48
+typedoc-plugin-markdown/dist/types/options.d.ts:52
 
 ***
 
@@ -317,7 +335,7 @@ Do not print breadcrumbs.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:52
+typedoc-plugin-markdown/dist/types/options.d.ts:56
 
 ***
 
@@ -333,7 +351,7 @@ Excludes grouping by kind so all members are rendered and sorted at the same lev
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:56
+typedoc-plugin-markdown/dist/types/options.d.ts:60
 
 ***
 
@@ -349,7 +367,7 @@ Do not print page header.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:60
+typedoc-plugin-markdown/dist/types/options.d.ts:64
 
 ***
 
@@ -365,7 +383,7 @@ Do not print page title.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:64
+typedoc-plugin-markdown/dist/types/options.d.ts:68
 
 ***
 
@@ -381,7 +399,7 @@ Sets the format of index items.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:68
+typedoc-plugin-markdown/dist/types/options.d.ts:72
 
 ***
 
@@ -397,7 +415,7 @@ Sets the format of property groups for interfaces.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:72
+typedoc-plugin-markdown/dist/types/options.d.ts:76
 
 ***
 
@@ -413,7 +431,7 @@ Determines which members are exported to their own file when `outputFileStrategy
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:76
+typedoc-plugin-markdown/dist/types/options.d.ts:80
 
 ***
 
@@ -429,7 +447,7 @@ Merges the resolved readme into the project index page.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:80
+typedoc-plugin-markdown/dist/types/options.d.ts:84
 
 ***
 
@@ -457,7 +475,7 @@ Configures how the navigation model will be generated.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:84
+typedoc-plugin-markdown/dist/types/options.d.ts:88
 
 ***
 
@@ -473,7 +491,7 @@ Determines how output files are generated.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:92
+typedoc-plugin-markdown/dist/types/options.d.ts:96
 
 ***
 
@@ -489,7 +507,7 @@ Sets the format of parameter and type parameter groups.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:96
+typedoc-plugin-markdown/dist/types/options.d.ts:100
 
 ***
 
@@ -505,7 +523,7 @@ Preserve anchor casing when generating link to symbols.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:100
+typedoc-plugin-markdown/dist/types/options.d.ts:104
 
 ***
 
@@ -521,7 +539,7 @@ Sets the format of property groups for interfaces and classes.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:104
+typedoc-plugin-markdown/dist/types/options.d.ts:108
 
 ***
 
@@ -537,7 +555,7 @@ Sets the format of style for property members for interfaces and classes.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:108
+typedoc-plugin-markdown/dist/types/options.d.ts:112
 
 ***
 
@@ -553,7 +571,7 @@ Specify the base path for all urls.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:112
+typedoc-plugin-markdown/dist/types/options.d.ts:116
 
 ***
 
@@ -569,7 +587,7 @@ Sanitize HTML and JSX inside JsDoc comments.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:116
+typedoc-plugin-markdown/dist/types/options.d.ts:120
 
 ***
 
@@ -613,7 +631,7 @@ Control how table columns are configured and displayed.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:120
+typedoc-plugin-markdown/dist/types/options.d.ts:124
 
 ***
 
@@ -653,7 +671,7 @@ Change specific text placeholders in the template.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:132
+typedoc-plugin-markdown/dist/types/options.d.ts:136
 
 ***
 
@@ -669,7 +687,7 @@ Sets the format of style for type declaration members.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:143
+typedoc-plugin-markdown/dist/types/options.d.ts:147
 
 ***
 
@@ -685,7 +703,7 @@ Wraps signatures and declarations in code blocks.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:147
+typedoc-plugin-markdown/dist/types/options.d.ts:151
 
 ***
 
@@ -701,7 +719,7 @@ Add HTML named anchors to headings and table rows.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:151
+typedoc-plugin-markdown/dist/types/options.d.ts:155
 
 ***
 
@@ -717,4 +735,4 @@ Use HTML encoded entities for angle brackets.
 
 #### Defined in
 
-typedoc-plugin-markdown/dist/types/options.d.ts:155
+typedoc-plugin-markdown/dist/types/options.d.ts:159
diff --git a/devguide/typedoc-plugin-markdown/documents/Getting-Started.md b/devguide/typedoc-plugin-markdown/documents/Getting-Started.md
index 14916a09..76cb9158 100644
--- a/devguide/typedoc-plugin-markdown/documents/Getting-Started.md
+++ b/devguide/typedoc-plugin-markdown/documents/Getting-Started.md
@@ -6,30 +6,25 @@ This guide provides some high-level steps with some typical development tasks.
 
 ## Contents
 
-* [Setup](#setup)
 * [Development Playground](#development-playground)
   * [Run Playground Docs](#run-playground-docs)
   * [View Playground Docs](#view-playground-docs)
   * [Perform a Simple Task](#perform-a-simple-task)
 * [Next Steps](#next-steps)
 
-## Setup
+## Development Playground
 
-Please see [Machine Setup]() for general setup instructions.
+To get started you can create a simple task of running a playground and editing a template.
 
-If you are setup, you can start by navigating to the package directory.
+### Run Playground Docs
+
+Start by navigating to the package directory:
 
 ```shell
 cd packages/typedoc-plugin-markdown
 ```
 
-## Development Playground
-
-To get started you can create a simple task of running a playground and editing a template.
-
-### Run Playground Docs
-
-Run the playground from the project root.
+Run the playground from the project root:
 
 ```shell
 npm run playground
diff --git a/devguide/typedoc-plugin-markdown/libs/namespaces/utils/README.md b/devguide/typedoc-plugin-markdown/libs/namespaces/utils/README.md
index e2fa7331..52eaf157 100644
--- a/devguide/typedoc-plugin-markdown/libs/namespaces/utils/README.md
+++ b/devguide/typedoc-plugin-markdown/libs/namespaces/utils/README.md
@@ -13,7 +13,6 @@ General utility pure functions.
 * [formatTableCell()](#formattablecell)
 * [getFileNameWithExtension()](#getfilenamewithextension)
 * [isQuoted()](#isquoted)
-* [normalizeLineBreaks()](#normalizelinebreaks)
 * [removeFirstScopedDirectory()](#removefirstscopeddirectory)
 * [removeLineBreaks()](#removelinebreaks)
 * [sanitizeComments()](#sanitizecomments)
@@ -168,26 +167,6 @@ Returns a filename with extension while normalizing both the input name and inpu
 
 ***
 
-## normalizeLineBreaks()
-
-> **normalizeLineBreaks**(`str`): `string`
-
-### Parameters
-
-| Parameter | Type     |
-| --------- | -------- |
-| `str`     | `string` |
-
-### Returns
-
-`string`
-
-### Defined in
-
-[packages/typedoc-plugin-markdown/src/libs/utils/normalize-line-breaks.ts:1](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/libs/utils/normalize-line-breaks.ts#L1)
-
-***
-
 ## removeFirstScopedDirectory()
 
 > **removeFirstScopedDirectory**(`urlString`): `string`
diff --git a/devguide/typedoc-plugin-markdown/options/namespaces/declarations/README.md b/devguide/typedoc-plugin-markdown/options/namespaces/declarations/README.md
index 9df746fc..27d02e2b 100644
--- a/devguide/typedoc-plugin-markdown/options/namespaces/declarations/README.md
+++ b/devguide/typedoc-plugin-markdown/options/namespaces/declarations/README.md
@@ -27,6 +27,7 @@ The JSDoc comments will also be used in the public facing documentation.
   * [useCodeBlocks](#usecodeblocks)
   * [expandObjects](#expandobjects)
   * [expandParameters](#expandparameters)
+  * [blockTagsPreserveOrder](#blocktagspreserveorder)
   * [indexFormat](#indexformat)
   * [parametersFormat](#parametersformat)
   * [interfacePropertiesFormat](#interfacepropertiesformat)
@@ -527,6 +528,43 @@ This option should be set when a full type representation is preferred.
 
 ***
 
+### blockTagsPreserveOrder
+
+> `const` **blockTagsPreserveOrder**: `Partial`\<[`DeclarationOption`](https://typedoc.org/api/types/Configuration.DeclarationOption.html)>
+
+By default block tags (such as `@example`, `@remarks`, `@deprecated`) are rendered after "Parameters", "Returns" and "Type declaration" sections for signatures and declarations.
+
+The rationale is that comment block tags often contain more detailed, supplementary information and are typically secondary to understanding the primary use of the symbol,
+
+Use this option to preserve the position of the tag content with the comment summary.
+
+#### Example
+
+```ts
+["@example", "@deprecated"]
+```
+
+#### Default Value
+
+```ts
+{
+    help: 'Specifies comment block tags that should preserve their position in relation to the comment summary.',
+    type: ParameterType.Array,
+    defaultValue: [],
+    validate(value, i18n) {
+        if (!value.every((tag) => typeof tag === 'string' && /^@[a-zA-Z][a-zA-Z0-9]*$/.test(tag))) {
+            throw new Error(i18n.option_0_values_must_be_array_of_tags('blockTags'));
+        }
+    },
+}
+```
+
+#### Defined in
+
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:350](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L350)
+
+***
+
 ### indexFormat
 
 > `const` **indexFormat**: `Partial`\<[`DeclarationOption`](https://typedoc.org/api/types/Configuration.DeclarationOption.html)>
@@ -552,7 +590,7 @@ When table style is selected the following will be the behaviour:
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:350](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L350)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:376](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L376)
 
 ***
 
@@ -579,7 +617,7 @@ This option specifies the output format for parameters and type parameters of fu
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:366](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L366)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:392](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L392)
 
 ***
 
@@ -606,7 +644,7 @@ This option specifies the output format for interface properties:
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:382](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L382)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:408](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L408)
 
 ***
 
@@ -633,7 +671,7 @@ This option specifies the output format for class properties:
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:398](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L398)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:424](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L424)
 
 ***
 
@@ -660,7 +698,7 @@ This option specifies the output format for enumeration members:
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:414](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L414)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:440](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L440)
 
 ***
 
@@ -687,7 +725,7 @@ This option specifies the output format for type declaration of variables and ty
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:430](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L430)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:456](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L456)
 
 ***
 
@@ -716,7 +754,7 @@ Note this options will only take effect when `propertiesFormat` is set to `list`
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:448](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L448)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:474](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L474)
 
 ***
 
@@ -724,8 +762,7 @@ Note this options will only take effect when `propertiesFormat` is set to `list`
 
 > `const` **tableColumnSettings**: `Partial`\<[`DeclarationOption`](https://typedoc.org/api/types/Configuration.DeclarationOption.html)>
 
-By default, all available data for symbols are displayed in table columns.
-For some reflections this can result in several columns.
+By default, all available data for symbols are displayed in table columns which can result in several columns in certain use-cases.
 
 This option allows you to control the visibility of columns, prioritizing readability over displaying complete data.
 In addition you can control the alignment of the header text.
@@ -750,7 +787,7 @@ In addition you can control the alignment of the header text.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:478](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L478)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:503](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L503)
 
 ## Utility
 
@@ -780,7 +817,7 @@ If undefined all urls will be relative.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:499](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L499)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:524](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L524)
 
 ***
 
@@ -812,7 +849,7 @@ This option would typically be used when source code comes from an external libr
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:520](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L520)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:545](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L545)
 
 ***
 
@@ -840,7 +877,7 @@ This option should be used when parsers require a custom anchor prefix.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:533](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L533)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:558](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L558)
 
 ***
 
@@ -865,7 +902,7 @@ This option should be used if there are issues with anchoring to symbols within
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:547](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L547)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:572](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L572)
 
 ***
 
@@ -888,7 +925,7 @@ However, using HTML entities (`&lt;` and `&gt;`) might be preferable to avoid an
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:559](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L559)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:584](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L584)
 
 ***
 
@@ -912,7 +949,7 @@ This option can be used for engines that require the preservation of anchor link
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:572](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L572)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:597](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L597)
 
 ***
 
@@ -953,7 +990,7 @@ If you are looking for general localization support please see [localization]().
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:592](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L592)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:617](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L617)
 
 ***
 
@@ -1003,4 +1040,4 @@ export function load(app: MarkdownApplication) {
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/options/declarations.ts:642](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L642)
+[packages/typedoc-plugin-markdown/src/options/declarations.ts:667](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/options/declarations.ts#L667)
diff --git a/devguide/typedoc-plugin-markdown/types/interfaces/PluginOptions.md b/devguide/typedoc-plugin-markdown/types/interfaces/PluginOptions.md
index 2a15449c..62a3b593 100644
--- a/devguide/typedoc-plugin-markdown/types/interfaces/PluginOptions.md
+++ b/devguide/typedoc-plugin-markdown/types/interfaces/PluginOptions.md
@@ -9,6 +9,7 @@ Describes the options declared by the plugin.
 * [Extended by](#extended-by)
 * [Properties](#properties)
   * [anchorPrefix](#anchorprefix)
+  * [blockTagsPreserveOrder](#blocktagspreserveorder)
   * [classPropertiesFormat](#classpropertiesformat)
   * [entryFileName](#entryfilename)
   * [entryModule](#entrymodule)
@@ -75,6 +76,18 @@ Custom anchor prefix when anchoring to in-page symbols.
 
 ***
 
+### blockTagsPreserveOrder
+
+> **blockTagsPreserveOrder**: `string`\[]
+
+Specifies comment block tags that should preserve their position in relation to the comment summary.
+
+#### Defined in
+
+[packages/typedoc-plugin-markdown/src/types/options.ts:16](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L16)
+
+***
+
 ### classPropertiesFormat
 
 > **classPropertiesFormat**: `"table"` | `"list"` | `"htmlTable"`
@@ -83,7 +96,7 @@ Sets the format of property groups for classes.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:16](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L16)
+[packages/typedoc-plugin-markdown/src/types/options.ts:21](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L21)
 
 ***
 
@@ -95,7 +108,7 @@ The file name of the entry page.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:21](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L21)
+[packages/typedoc-plugin-markdown/src/types/options.ts:26](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L26)
 
 ***
 
@@ -107,7 +120,7 @@ The name of a module that should act as the root page for the documentation.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:26](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L26)
+[packages/typedoc-plugin-markdown/src/types/options.ts:31](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L31)
 
 ***
 
@@ -119,7 +132,7 @@ Sets the format of enumeration members.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:31](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L31)
+[packages/typedoc-plugin-markdown/src/types/options.ts:36](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L36)
 
 ***
 
@@ -133,7 +146,7 @@ This option has been renamed hideGroupHeadings to better reflect its purpose.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:36](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L36)
+[packages/typedoc-plugin-markdown/src/types/options.ts:41](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L41)
 
 ***
 
@@ -145,7 +158,7 @@ Exclude writing @ scope directories in paths.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:41](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L41)
+[packages/typedoc-plugin-markdown/src/types/options.ts:46](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L46)
 
 ***
 
@@ -157,7 +170,7 @@ Expand objects inside declarations.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:46](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L46)
+[packages/typedoc-plugin-markdown/src/types/options.ts:51](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L51)
 
 ***
 
@@ -169,7 +182,7 @@ Expand parameters in signature parentheses to display type information.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:51](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L51)
+[packages/typedoc-plugin-markdown/src/types/options.ts:56](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L56)
 
 ***
 
@@ -181,7 +194,7 @@ Specify the file extension for generated output files.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:56](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L56)
+[packages/typedoc-plugin-markdown/src/types/options.ts:61](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L61)
 
 ***
 
@@ -193,7 +206,7 @@ Flatten output files to a single directory.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:61](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L61)
+[packages/typedoc-plugin-markdown/src/types/options.ts:66](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L66)
 
 ***
 
@@ -205,7 +218,7 @@ Do not print breadcrumbs.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:66](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L66)
+[packages/typedoc-plugin-markdown/src/types/options.ts:71](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L71)
 
 ***
 
@@ -217,7 +230,7 @@ Excludes grouping by kind so all members are rendered and sorted at the same lev
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:71](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L71)
+[packages/typedoc-plugin-markdown/src/types/options.ts:76](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L76)
 
 ***
 
@@ -229,7 +242,7 @@ Do not print page header.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:76](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L76)
+[packages/typedoc-plugin-markdown/src/types/options.ts:81](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L81)
 
 ***
 
@@ -241,7 +254,7 @@ Do not print page title.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:81](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L81)
+[packages/typedoc-plugin-markdown/src/types/options.ts:86](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L86)
 
 ***
 
@@ -253,7 +266,7 @@ Sets the format of index items.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:86](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L86)
+[packages/typedoc-plugin-markdown/src/types/options.ts:91](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L91)
 
 ***
 
@@ -265,7 +278,7 @@ Sets the format of property groups for interfaces.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:91](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L91)
+[packages/typedoc-plugin-markdown/src/types/options.ts:96](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L96)
 
 ***
 
@@ -277,7 +290,7 @@ Determines which members are exported to their own file when `outputFileStrategy
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:96](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L96)
+[packages/typedoc-plugin-markdown/src/types/options.ts:101](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L101)
 
 ***
 
@@ -289,7 +302,7 @@ Merges the resolved readme into the project index page.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:108](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L108)
+[packages/typedoc-plugin-markdown/src/types/options.ts:113](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L113)
 
 ***
 
@@ -313,7 +326,7 @@ Configures how the navigation model will be generated.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:113](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L113)
+[packages/typedoc-plugin-markdown/src/types/options.ts:118](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L118)
 
 ***
 
@@ -325,7 +338,7 @@ Determines how output files are generated.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:122](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L122)
+[packages/typedoc-plugin-markdown/src/types/options.ts:127](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L127)
 
 ***
 
@@ -337,7 +350,7 @@ Sets the format of parameter and type parameter groups.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:127](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L127)
+[packages/typedoc-plugin-markdown/src/types/options.ts:132](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L132)
 
 ***
 
@@ -349,7 +362,7 @@ Preserve anchor casing when generating link to symbols.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:132](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L132)
+[packages/typedoc-plugin-markdown/src/types/options.ts:137](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L137)
 
 ***
 
@@ -361,7 +374,7 @@ Sets the format of property groups for interfaces and classes.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:137](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L137)
+[packages/typedoc-plugin-markdown/src/types/options.ts:142](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L142)
 
 ***
 
@@ -373,7 +386,7 @@ Sets the format of style for property members for interfaces and classes.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:142](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L142)
+[packages/typedoc-plugin-markdown/src/types/options.ts:147](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L147)
 
 ***
 
@@ -385,7 +398,7 @@ Specify the base path for all urls.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:147](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L147)
+[packages/typedoc-plugin-markdown/src/types/options.ts:152](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L152)
 
 ***
 
@@ -397,7 +410,7 @@ Sanitize HTML and JSX inside JsDoc comments.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:152](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L152)
+[packages/typedoc-plugin-markdown/src/types/options.ts:157](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L157)
 
 ***
 
@@ -437,7 +450,7 @@ Control how table columns are configured and displayed.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:157](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L157)
+[packages/typedoc-plugin-markdown/src/types/options.ts:162](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L162)
 
 ***
 
@@ -473,7 +486,7 @@ Change specific text placeholders in the template.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:170](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L170)
+[packages/typedoc-plugin-markdown/src/types/options.ts:175](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L175)
 
 ***
 
@@ -485,7 +498,7 @@ Sets the format of style for type declaration members.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:182](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L182)
+[packages/typedoc-plugin-markdown/src/types/options.ts:187](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L187)
 
 ***
 
@@ -497,7 +510,7 @@ Wraps signatures and declarations in code blocks.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:187](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L187)
+[packages/typedoc-plugin-markdown/src/types/options.ts:192](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L192)
 
 ***
 
@@ -509,7 +522,7 @@ Add HTML named anchors to headings and table rows.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:192](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L192)
+[packages/typedoc-plugin-markdown/src/types/options.ts:197](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L197)
 
 ***
 
@@ -521,4 +534,4 @@ Use HTML encoded entities for angle brackets.
 
 #### Defined in
 
-[packages/typedoc-plugin-markdown/src/types/options.ts:197](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L197)
+[packages/typedoc-plugin-markdown/src/types/options.ts:202](https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/types/options.ts#L202)
diff --git a/devtools/packages/prebuild-options/tasks/generate-docs.ts b/devtools/packages/prebuild-options/tasks/generate-docs.ts
index c850d015..77a05721 100644
--- a/devtools/packages/prebuild-options/tasks/generate-docs.ts
+++ b/devtools/packages/prebuild-options/tasks/generate-docs.ts
@@ -154,9 +154,7 @@ ${presetsJson}
             `<Callout type="warning">Deprecated: ${option.deprecated}</Callout>`,
           );
         } else {
-          out.push(
-            `<Callout emoji="${getEmoji(categoryName)}">${option.help}</Callout>`,
-          );
+          out.push(`<Callout emoji="${getEmoji()}">${option.help}</Callout>`);
         }
 
         const meta: string[] = [];
@@ -255,18 +253,12 @@ ${JSON.stringify(
   }
 }
 
-function getEmoji(categoryName: string) {
-  /*if (categoryName === 'Output') {
-    return '📁';
-  }
-  if (categoryName === 'Utilities') {
-    return '⚙️';
-  }*/
+function getEmoji() {
   return '💡';
 }
 
 function getType(option: any) {
-  if (option.type === ParameterType.Array && option.defaultValue) {
+  if (option.type === ParameterType.Array && option.defaultValue?.length) {
     return `Accepts an array of the following values ${option.defaultValue
       .toString()
       .split(',')
@@ -274,6 +266,10 @@ function getType(option: any) {
       .join(' ')}.`;
   }
 
+  if (option.type === ParameterType.Array) {
+    return 'Accepts an array of string values.';
+  }
+
   if (option.type === ParameterType.String) {
     return 'Accepts a string value.';
   }
diff --git a/devtools/packages/prebuild-options/tasks/generate-models.ts b/devtools/packages/prebuild-options/tasks/generate-models.ts
index 508212b0..0f902f16 100644
--- a/devtools/packages/prebuild-options/tasks/generate-models.ts
+++ b/devtools/packages/prebuild-options/tasks/generate-models.ts
@@ -120,23 +120,23 @@ ${name}: ${getType(name, option, true)};`,
   }
 
   ${mixedTypes
-    ?.filter(([name]) => !ignoreTypes.includes(name))
-    .map(([name, option]) => {
-      return `
+      ?.filter(([name]) => !ignoreTypes.includes(name))
+      .map(([name, option]) => {
+        return `
   /**
    * ${getComments(name)}
    */
   export interface ${capitalize(name)} {
       ${Object.entries(option.defaultValue as any)
-        .map(
-          ([key, value]) =>
-            `'${key}'${value === undefined ? '?' : ''}: ${getValueType(value)}`,
-        )
-        .join(';')}
+            .map(
+              ([key, value]) =>
+                `'${key}'${value === undefined ? '?' : ''}: ${getValueType(value)}`,
+            )
+            .join(';')}
   }
     `;
-    })
-    .join('\n')}
+      })
+      .join('\n')}
   `);
 
   const optionsModelFile = path.join(process.cwd(), 'src/types/options.ts');
@@ -175,7 +175,7 @@ function getType(
   option: Partial<DeclarationOption>,
   isInterface = false,
 ) {
-  if (option.type === ParameterType.Array && option.defaultValue) {
+  if (option.type === ParameterType.Array && option.defaultValue?.length) {
     return `(${option.defaultValue
       .toString()
       .split(',')
@@ -193,7 +193,7 @@ function getType(
     return 'string';
   }
   if (option.type === ParameterType.Array) {
-    return 'any[]';
+    return 'string[]';
   }
   if (option.type === ParameterType.Flags && option.defaults) {
     return `{${Object.keys(option.defaults)
diff --git a/docs/pages/api-docs/Interface.PluginOptions.mdx b/docs/pages/api-docs/Interface.PluginOptions.mdx
index b76a6392..3eeb85d8 100644
--- a/docs/pages/api-docs/Interface.PluginOptions.mdx
+++ b/docs/pages/api-docs/Interface.PluginOptions.mdx
@@ -12,6 +12,14 @@ Custom anchor prefix when anchoring to in-page symbols.
 
 ***
 
+### blockTagsPreserveOrder
+
+> **blockTagsPreserveOrder**: `string`[]
+
+Specifies comment block tags that should preserve their position in relation to the comment summary.
+
+***
+
 ### classPropertiesFormat
 
 > **classPropertiesFormat**: `"table"` \| `"list"` \| `"htmlTable"`
diff --git a/docs/pages/docs/_meta.js b/docs/pages/docs/_meta.js
index 117678c2..19a26181 100644
--- a/docs/pages/docs/_meta.js
+++ b/docs/pages/docs/_meta.js
@@ -15,7 +15,7 @@ export default {
     type: 'separator',
     title: 'Support',
   },
+  'migration-guide': 'Migration Guide (v4)',
   versioning: '',
-  'v4-migration-guide': 'v4 Migration Guide',
-  CHANGELOG: 'v4 Changelog',
+  CHANGELOG: 'Changelog',
 };
diff --git a/docs/pages/docs/v4-migration-guide.mdx b/docs/pages/docs/migration-guide.mdx
similarity index 99%
rename from docs/pages/docs/v4-migration-guide.mdx
rename to docs/pages/docs/migration-guide.mdx
index 546a67a5..f3ddeeb7 100644
--- a/docs/pages/docs/v4-migration-guide.mdx
+++ b/docs/pages/docs/migration-guide.mdx
@@ -1,6 +1,6 @@
 import { Callout } from 'nextra/components';
 
-# v4 Migration Guide
+# Migration Guide (v4)
 
 <Callout type="info">
   v4.0 is a major release that includes a number of bug fixes, new features and
diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx
index d63ccd71..159ea49a 100644
--- a/docs/pages/docs/options.mdx
+++ b/docs/pages/docs/options.mdx
@@ -31,6 +31,7 @@ Options that are used to configure how the output is structured and displayed.
 - [--useCodeBlocks](./options/display-options.mdx#--usecodeblocks)
 - [--expandObjects](./options/display-options.mdx#--expandobjects)
 - [--expandParameters](./options/display-options.mdx#--expandparameters)
+- [--blockTagsPreserveOrder](./options/display-options.mdx#--blocktagspreserveorder)
 - [--indexFormat](./options/display-options.mdx#--indexformat)
 - [--parametersFormat](./options/display-options.mdx#--parametersformat)
 - [--interfacePropertiesFormat](./options/display-options.mdx#--interfacepropertiesformat)
diff --git a/docs/pages/docs/options/display-options.mdx b/docs/pages/docs/options/display-options.mdx
index b0225d7b..0ff20c70 100644
--- a/docs/pages/docs/options/display-options.mdx
+++ b/docs/pages/docs/options/display-options.mdx
@@ -111,6 +111,27 @@ This option should be set when a full type representation is preferred.
 }
 ```
 
+## --blockTagsPreserveOrder
+
+<Callout emoji="💡">
+  Specifies comment block tags that should preserve their position in relation
+  to the comment summary.
+</Callout>
+
+> Accepts an array of string values.
+
+By default block tags (such as `@example`, `@remarks`, `@deprecated`) are rendered after "Parameters", "Returns" and "Type declaration" sections for signatures and declarations.
+
+The rationale is that comment block tags often contain more detailed, supplementary information and are typically secondary to understanding the primary use of the symbol,
+
+Use this option to preserve the position of the tag content with the comment summary.
+
+```json filename="typedoc.json"
+{
+  "blockTagsPreserveOrder": ["@example", "@deprecated"]
+}
+```
+
 ## --indexFormat
 
 <Callout emoji="💡">Sets the format of index items.</Callout>
@@ -255,8 +276,7 @@ Note this options will only take effect when `propertiesFormat` is set to `list`
 
 >
 
-By default, all available data for symbols are displayed in table columns.
-For some reflections this can result in several columns.
+By default, all available data for symbols are displayed in table columns which can result in several columns in certain use-cases.
 
 This option allows you to control the visibility of columns, prioritizing readability over displaying complete data.
 In addition you can control the alignment of the header text.
diff --git a/docs/public/schema.json b/docs/public/schema.json
index e33e0a6a..fbc0a3aa 100644
--- a/docs/public/schema.json
+++ b/docs/public/schema.json
@@ -11,6 +11,14 @@
           "type": "string",
           "description": "[typedoc-plugin-markdown] Custom anchor prefix when anchoring to in-page symbols."
         },
+        "blockTagsPreserveOrder": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "[typedoc-plugin-markdown] Specifies comment block tags that should preserve their position in relation to the comment summary.",
+          "default": []
+        },
         "classPropertiesFormat": {
           "type": "string",
           "enum": [
@@ -285,6 +293,10 @@
         "useHTMLAnchors": {
           "type": "boolean",
           "description": "[typedoc-plugin-markdown] Add HTML named anchors to headings and table rows."
+        },
+        "useHTMLEncodedBrackets": {
+          "type": "boolean",
+          "description": "[typedoc-plugin-markdown] Use HTML encoded entities for angle brackets."
         }
       },
       "description": "Describes the options declared by the plugin.",
diff --git a/packages/typedoc-plugin-markdown/src/_typedoc.d.ts b/packages/typedoc-plugin-markdown/src/_typedoc.d.ts
index e190a2f1..263f719c 100644
--- a/packages/typedoc-plugin-markdown/src/_typedoc.d.ts
+++ b/packages/typedoc-plugin-markdown/src/_typedoc.d.ts
@@ -3,6 +3,7 @@ import { ManuallyValidatedOption } from 'typedoc';
 declare module 'typedoc' {
   export interface TypeDocOptionMap {
     anchorPrefix: string;
+    blockTagsPreserveOrder: string[];
     classPropertiesFormat: 'list' | 'table' | 'htmlTable';
     entryFileName: string;
     entryModule: string;
diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts
index d249a6dc..781451af 100644
--- a/packages/typedoc-plugin-markdown/src/options/declarations.ts
+++ b/packages/typedoc-plugin-markdown/src/options/declarations.ts
@@ -336,6 +336,32 @@ export const expandParameters: Partial<DeclarationOption> = {
   defaultValue: false,
 };
 
+/**
+ * By default block tags (such as `@example`, `@remarks`, `@deprecated`) are rendered after "Parameters", "Returns" and "Type declaration" sections for signatures and declarations.
+ *
+ * The rationale is that comment block tags often contain more detailed, supplementary information and are typically secondary to understanding the primary use of the symbol,
+ *
+ * Use this option to preserve the position of the tag content with the comment summary.
+ *
+ * @example ["@example", "@deprecated"]
+ *
+ * @category Display
+ */
+export const blockTagsPreserveOrder: Partial<DeclarationOption> = {
+  help: 'Specifies comment block tags that should preserve their position in relation to the comment summary.',
+  type: ParameterType.Array,
+  defaultValue: [],
+  validate(value, i18n) {
+    if (
+      !value.every(
+        (tag) => typeof tag === 'string' && /^@[a-zA-Z][a-zA-Z0-9]*$/.test(tag),
+      )
+    ) {
+      throw new Error(i18n.option_0_values_must_be_array_of_tags('blockTags'));
+    }
+  },
+};
+
 /**
  * This option renders index items either as a simple unordered list or in a table.
  *
@@ -467,8 +493,7 @@ export const propertiesFormat: Partial<DeclarationOption> = {
 };
 
 /**
- * By default, all available data for symbols are displayed in table columns.
- * For some reflections this can result in several columns.
+ * By default, all available data for symbols are displayed in table columns which can result in several columns in certain use-cases.
  *
  * This option allows you to control the visibility of columns, prioritizing readability over displaying complete data.
  * In addition you can control the alignment of the header text.
diff --git a/packages/typedoc-plugin-markdown/src/renderer/overrides.ts b/packages/typedoc-plugin-markdown/src/renderer/overrides.ts
index 27b0a032..ecec564b 100644
--- a/packages/typedoc-plugin-markdown/src/renderer/overrides.ts
+++ b/packages/typedoc-plugin-markdown/src/renderer/overrides.ts
@@ -99,6 +99,14 @@ export async function render(
       }
     });
 
+  // copy resolved files to media directory
+  const media = path.join(outputDirectory, '_media');
+  const toCopy = project.files.getNameToAbsoluteMap();
+  for (const [fileName, absolute] of toCopy.entries()) {
+    copySync(absolute, path.join(media, fileName));
+  }
+
+  // process postRenderAsyncJobs
   await Promise.all(this.postRenderAsyncJobs.map((job) => job(output)));
 
   this.postRenderAsyncJobs = [];
@@ -141,3 +149,16 @@ function nicePath(absPath: string) {
 function normalizePath(path: string) {
   return path.replace(/\\/g, '/');
 }
+
+function copySync(src: string, dest: string): void {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    const contained = fs.readdirSync(src);
+    contained.forEach((file) =>
+      copySync(path.join(src, file), path.join(dest, file)),
+    );
+  } else if (stat.isFile()) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-parts.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-parts.ts
index 13143bd1..2ea39ea1 100644
--- a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-parts.ts
+++ b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-comment-parts.ts
@@ -42,6 +42,27 @@ export function getCommentParts(
             break;
         }
         break;
+      case 'relative-link':
+        switch (typeof part.target) {
+          case 'number':
+            {
+              const reflection = this.page.project.files.resolve(part.target);
+              if (typeof reflection === 'object' && reflection.url) {
+                md.push(this.getRelativeUrl(reflection.url));
+                break;
+              }
+              const fileName = this.page.project.files.getName(part.target);
+              if (fileName) {
+                md.push(this.getRelativeUrl(`_media/${fileName}`));
+                break;
+              }
+            }
+            break;
+          case 'undefined':
+            md.push(part.text);
+            break;
+        }
+        break;
       default:
         md.push('');
     }
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts
index 76886749..6e33fb66 100644
--- a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts
+++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts
@@ -49,8 +49,15 @@ export function comment(
     }
   }
 
+  const blockTagsPreserveOrder = this.options.getValue(
+    'blockTagsPreserveOrder',
+  ) as string[];
+
+  const showTags =
+    opts.showTags || (opts.showSummary && blockTagsPreserveOrder.length > 0);
+
   // Add Tags
-  if (opts.showTags && model.blockTags?.length) {
+  if (showTags && model.blockTags?.length > 0) {
     const blockTags = model.blockTags.reduce(
       (previous: CommentTag[], current: CommentTag) => {
         if (current.tag === '@example') {
@@ -80,6 +87,14 @@ export function comment(
 
     const tags = blockTags
       .filter((tag) => !filteredBlockTags.includes(tag.tag))
+      .filter((tag) => {
+        if (!opts.isTableColumn && blockTagsPreserveOrder.length) {
+          return opts.showSummary
+            ? blockTagsPreserveOrder.includes(tag.tag)
+            : !blockTagsPreserveOrder.includes(tag.tag);
+        }
+        return true;
+      })
       .filter(
         (tag) =>
           !opts.isTableColumn ||
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
index c38361a9..c9dbdb07 100644
--- a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
+++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.declaration.ts
@@ -39,19 +39,18 @@ export function declaration(
   const typeDeclaration = (model.type as any)
     ?.declaration as DeclarationReflection;
 
-  if (
-    !typeDeclaration?.signatures?.every((signature) =>
-      Boolean(signature.comment),
-    )
-  ) {
-    if (model.comment) {
-      md.push(
-        this.partials.comment(model.comment, {
-          headingLevel: opts.headingLevel,
-          showTags: true,
-        }),
-      );
-    }
+  const showComments = !typeDeclaration?.signatures?.every((signature) =>
+    Boolean(signature.comment),
+  );
+
+  if (showComments && model.comment) {
+    md.push(
+      this.partials.comment(model.comment, {
+        headingLevel: opts.headingLevel,
+        showSummary: true,
+        showTags: false,
+      }),
+    );
   }
 
   if (model.type instanceof IntersectionType) {
@@ -162,6 +161,16 @@ export function declaration(
     }
   }
 
+  if (showComments && model.comment) {
+    md.push(
+      this.partials.comment(model.comment, {
+        headingLevel: opts.headingLevel,
+        showSummary: false,
+        showTags: true,
+      }),
+    );
+  }
+
   md.push(
     this.partials.inheritance(model, { headingLevel: opts.headingLevel }),
   );
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts
index a1a23b3f..4fec230d 100644
--- a/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts
+++ b/packages/typedoc-plugin-markdown/src/theme/context/partials/member.signature.ts
@@ -29,6 +29,7 @@ export function signature(
       this.partials.comment(modelComments, {
         headingLevel: options.headingLevel,
         showTags: false,
+        showSummary: true,
       }),
     );
   }
@@ -86,6 +87,7 @@ export function signature(
     md.push(
       this.partials.comment(modelComments, {
         headingLevel: options.headingLevel,
+        showTags: true,
         showSummary: false,
       }),
     );
diff --git a/packages/typedoc-plugin-markdown/src/types/options.ts b/packages/typedoc-plugin-markdown/src/types/options.ts
index d3aaca1e..88871c9f 100644
--- a/packages/typedoc-plugin-markdown/src/types/options.ts
+++ b/packages/typedoc-plugin-markdown/src/types/options.ts
@@ -10,6 +10,11 @@ export interface PluginOptions {
    */
   anchorPrefix: string;
 
+  /**
+   * Specifies comment block tags that should preserve their position in relation to the comment summary.
+   */
+  blockTagsPreserveOrder: string[];
+
   /**
    * Sets the format of property groups for classes.
    */
diff --git a/packages/typedoc-plugin-markdown/supporting-docs/internal/getting-started.md b/packages/typedoc-plugin-markdown/supporting-docs/internal/getting-started.md
index fece44c6..deaea144 100644
--- a/packages/typedoc-plugin-markdown/supporting-docs/internal/getting-started.md
+++ b/packages/typedoc-plugin-markdown/supporting-docs/internal/getting-started.md
@@ -7,23 +7,19 @@ description: How to start developing locally.
 
 This guide provides some high-level steps with some typical development tasks.
 
-## Setup
+## Development Playground
 
-Please see [Machine Setup](../../README.md) for general setup instructions.
+To get started you can create a simple task of running a playground and editing a template.
 
-If you are setup, you can start by navigating to the package directory.
+### Run Playground Docs
+
+Start by navigating to the package directory:
 
 ```shell
 cd packages/typedoc-plugin-markdown
 ```
 
-## Development Playground
-
-To get started you can create a simple task of running a playground and editing a template.
-
-### Run Playground Docs
-
-Run the playground from the project root.
+Run the playground from the project root:
 
 ```shell
 npm run playground
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts
index 78ae75f0..ef2a3ec1 100644
--- a/packages/typedoc-plugin-markdown/test/fixtures/config.ts
+++ b/packages/typedoc-plugin-markdown/test/fixtures/config.ts
@@ -17,6 +17,7 @@ const config: Record<string, Fixture> = {
         leftAlignHeaders: true,
       },
       excludePrivate: false,
+      blockTagsPreserveOrder: ['@deprecated', '@see'],
     },
     options: [
       {},
@@ -49,6 +50,7 @@ const config: Record<string, Fixture> = {
       tableColumnSettings: {
         leftAlignHeaders: true,
       },
+      blockTagsPreserveOrder: ['@deprecated', '@see'],
     },
     options: [
       {},
@@ -166,6 +168,7 @@ const config: Record<string, Fixture> = {
           hideValues: true,
           leftAlignHeaders: true,
         },
+        blockTagsPreserveOrder: ['@example'],
       },
     ],
   },
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts
index d819e4d2..713eef8c 100644
--- a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts
+++ b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts
@@ -21,6 +21,17 @@
  * - {@link https://www.google.com Google}
  * - {@linkcode https://www.google.com}
  *
+ * Relative Links:
+ *
+ * - [Relative Document](../../PROJECT_DOC_1.md)
+ * - [Relative Link](../../../groups/members/opts-1/index.md)
+ *
+ * Relative Image Links:
+ *
+ * <img src="../../media/logo.png" alt="Logo" />
+ *
+ * ![Logo](../../media/logo.svg)
+ *
  * @module
  *
  * @see
@@ -48,14 +59,6 @@
  * Some <p> html </p> inside codeblock
  * ```
  *
- * > media
- *
- * You can include media in doc comments:
- *
- * ![alt SomeAlt](media://logo.png)
- *
- * And include other files:
- *
  * > codeBlocks
  *
  * ```css
@@ -67,8 +70,6 @@
  * ```
  *
  * `single line <code> {block}`
- *
- * @document ../../inc/example.md
  */
 
 export interface CommentInterface {
@@ -268,3 +269,31 @@ export enum EnumMembersTable {
    */
   member1 = 'member1',
 }
+
+/**
+ * Function with block tags summary
+ *
+ * @example
+ * const x = 1;
+ *
+ * @see abc.com
+ *
+ * @remarks
+ *
+ * Other block tags
+ */
+export function functionWithBlockTags(x: string, y: string) {}
+
+/**
+ * Variable with block tags summary
+ *
+ * @example
+ * const x = 1;
+ *
+ * @remarks
+ *
+ * Other block tags
+ */
+export type typeWithBlockTags = {
+  x: string;
+};
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap
index b51610a3..14b1a3c3 100644
--- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap
+++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap
@@ -24,6 +24,17 @@ External links:
 - [Google](https://www.google.com)
 - [\`https://www.google.com\`](https://www.google.com)
 
+Relative Links:
+
+- [Relative Document](_media/PROJECT_DOC_1.md)
+- [Relative Link](../../../groups/members/opts-1/index.md)
+
+Relative Image Links:
+
+<img src="_media/logo.png" alt="Logo" />
+
+![Logo](_media/logo.svg)
+
 ## See
 
  - Comments for a tag
@@ -48,14 +59,6 @@ A <tag> in a code block
 Some <p> html </p> inside codeblock
 \`\`\`
 
-> media
-
-You can include media in doc comments:
-
-![alt SomeAlt](media://logo.png)
-
-And include other files:
-
 > codeBlocks
 
 \`\`\`css
@@ -68,10 +71,6 @@ And include other files:
 
 \`single line <code> {block}\`
 
-## Documents
-
-- [example](documents/example.md)
-
 ## Enumerations
 
 - [CommentEnum](enumerations/CommentEnum.md)
@@ -93,6 +92,7 @@ And include other files:
 ## Type Aliases
 
 - [TypeDeclarationTable](type-aliases/TypeDeclarationTable.md)
+- [typeWithBlockTags](type-aliases/typeWithBlockTags.md)
 
 ## Variables
 
@@ -104,12 +104,115 @@ And include other files:
 
 ## Functions
 
+- [functionWithBlockTags](functions/functionWithBlockTags.md)
 - [multipleExampleTags](functions/multipleExampleTags.md)
 - [parametersTable](functions/parametersTable.md)
 - [singleExampleTag](functions/singleExampleTag.md)
 "
 `;
 
+exports[`Comments should get function with block tags: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Function: functionWithBlockTags()
+
+> **functionWithBlockTags**(\`x\`, \`y\`): \`void\`
+
+Function with block tags summary
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| \`x\` | \`string\` |
+| \`y\` | \`string\` |
+
+## Returns
+
+\`void\`
+
+## Example
+
+\`\`\`ts
+const x = 1;
+\`\`\`
+
+## See
+
+abc.com
+
+## Remarks
+
+Other block tags
+
+## Source
+
+[index.ts:1](http://source-url)
+"
+`;
+
+exports[`Comments should get function with block tags: (Output File Strategy "members") (Option Group "2") 1`] = `
+"# Function: functionWithBlockTags()
+
+> **functionWithBlockTags**(\`x\`, \`y\`): \`void\`
+
+Function with block tags summary
+
+## Example
+
+\`\`\`ts
+const x = 1;
+\`\`\`
+
+## Parameters
+
+<table>
+<tr>
+<th align="left">Parameter</th>
+<th align="left">Type</th>
+</tr>
+<tr>
+<td>
+
+\`x\`
+
+</td>
+<td>
+
+\`string\`
+
+</td>
+</tr>
+<tr>
+<td>
+
+\`y\`
+
+</td>
+<td>
+
+\`string\`
+
+</td>
+</tr>
+</table>
+
+## Returns
+
+\`void\`
+
+## See
+
+abc.com
+
+## Remarks
+
+Other block tags
+
+## Source
+
+[index.ts:1](http://source-url)
+"
+`;
+
 exports[`Comments should get tables for emum: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Enumeration: EnumMembersTable
 
@@ -533,6 +636,79 @@ exports[`Comments should get tables for type declarations: (Output File Strategy
 "
 `;
 
+exports[`Comments should get variable with block tags: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Type Alias: typeWithBlockTags
+
+> **typeWithBlockTags**: \`object\`
+
+Variable with block tags summary
+
+## Type declaration
+
+| Name | Type | Source |
+| ------ | ------ | ------ |
+| \`x\` | \`string\` | [index.ts:1](http://source-url) |
+
+## Example
+
+\`\`\`ts
+const x = 1;
+\`\`\`
+
+## Remarks
+
+Other block tags
+
+## Source
+
+[index.ts:1](http://source-url)
+"
+`;
+
+exports[`Comments should get variable with block tags: (Output File Strategy "members") (Option Group "2") 1`] = `
+"# Type Alias: typeWithBlockTags
+
+> **typeWithBlockTags**: \\{\`x\`: \`string\`; \\}
+
+Variable with block tags summary
+
+## Example
+
+\`\`\`ts
+const x = 1;
+\`\`\`
+
+## Type declaration
+
+<table>
+<tr>
+<th align="left">Name</th>
+<th align="left">Type</th>
+</tr>
+<tr>
+<td>
+
+\`x\`
+
+</td>
+<td>
+
+\`string\`
+
+</td>
+</tr>
+</table>
+
+## Remarks
+
+Other block tags
+
+## Source
+
+[index.ts:1](http://source-url)
+"
+`;
+
 exports[`Comments should handle multiple example tags: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Function: multipleExampleTags()
 
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap
index a50ad0fa..ada8023a 100644
--- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap
+++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.function.spec.ts.snap
@@ -252,6 +252,10 @@ exports[`Function Reflection should compile function with a parameter: (Output F
 
 This is a function that is assigned to a variable.
 
+## See
+
+http://abc.com
+
 ## Parameters
 
 • **someParam**: \`number\`
@@ -262,10 +266,6 @@ This is some numeric parameter.
 
 \`number\`
 
-## See
-
-http://abc.com
-
 ## Source
 
 [functions.ts:1](http://source-url)
@@ -281,6 +281,10 @@ function basicFunction(someParam: number): number
 
 This is a function that is assigned to a variable.
 
+## See
+
+http://abc.com
+
 ## Parameters
 
 | Parameter | Type | Description |
@@ -291,10 +295,6 @@ This is a function that is assigned to a variable.
 
 \`number\`
 
-## See
-
-http://abc.com
-
 ## Source
 
 [functions.ts:1](http://source-url)
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
index 4e09a0e9..d1d379cf 100644
--- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
+++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
@@ -948,3 +948,61 @@ exports[`Urls should gets Urls for single package entry points: outputFileStrate
   "packages.md",
 ]
 `;
+
+exports[`Urls should gets Urls with media assets: outputFileStrategy: members 1`] = `
+[
+  "README.md",
+  "_media/PROJECT_DOC_1.md",
+  "_media/logo.png",
+  "_media/logo.svg",
+  "classes/BaseClassProperties.md",
+  "classes/ClassPropertiesTable.md",
+  "enumerations/CommentEnum.md",
+  "enumerations/EnumMembersTable.md",
+  "functions/functionWithBlockTags.md",
+  "functions/multipleExampleTags.md",
+  "functions/parametersTable.md",
+  "functions/singleExampleTag.md",
+  "interfaces/BaseInterfaceProperties.md",
+  "interfaces/CommentInterface.md",
+  "interfaces/CommentInterfaceExtended.md",
+  "interfaces/InterfacePropertiesTable.md",
+  "interfaces/SameName.md",
+  "type-aliases/TypeDeclarationTable.md",
+  "type-aliases/typeWithBlockTags.md",
+  "variables/SameName.md",
+  "variables/TypeDeclarationTable.md",
+  "variables/prop.md",
+  "variables/prop_with_underscore.md",
+  "variables/propb.md",
+]
+`;
+
+exports[`Urls should gets Urls with media assets: outputFileStrategy: members 2`] = `
+[
+  "Class.BaseClassProperties.md",
+  "Class.ClassPropertiesTable.md",
+  "Enumeration.CommentEnum.md",
+  "Enumeration.EnumMembersTable.md",
+  "Function.functionWithBlockTags.md",
+  "Function.multipleExampleTags.md",
+  "Function.parametersTable.md",
+  "Function.singleExampleTag.md",
+  "Interface.BaseInterfaceProperties.md",
+  "Interface.CommentInterface.md",
+  "Interface.CommentInterfaceExtended.md",
+  "Interface.InterfacePropertiesTable.md",
+  "Interface.SameName.md",
+  "README.md",
+  "TypeAlias.TypeDeclarationTable.md",
+  "TypeAlias.typeWithBlockTags.md",
+  "Variable.SameName.md",
+  "Variable.TypeDeclarationTable.md",
+  "Variable._prop_with_underscore.md",
+  "Variable.prop.md",
+  "Variable.propb.md",
+  "_media/PROJECT_DOC_1.md",
+  "_media/logo.png",
+  "_media/logo.svg",
+]
+`;
diff --git a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts
index ef29d610..0d6487d7 100644
--- a/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts
+++ b/packages/typedoc-plugin-markdown/test/specs/comments.spec.ts
@@ -49,4 +49,18 @@ describe(`Comments`, () => {
       '/Enumeration.EnumMembersTable.md',
     ]);
   });
+
+  test(`should get function with block tags`, () => {
+    expectFileToEqual('comments', 'members', [
+      '/functions/functionWithBlockTags.md',
+      '/Function.functionWithBlockTags.md',
+    ]);
+  });
+
+  test(`should get variable with block tags`, () => {
+    expectFileToEqual('comments', 'members', [
+      '/type-aliases/typeWithBlockTags.md',
+      '/TypeAlias.typeWithBlockTags.md',
+    ]);
+  });
 });
diff --git a/packages/typedoc-plugin-markdown/test/specs/urls.spec.ts b/packages/typedoc-plugin-markdown/test/specs/urls.spec.ts
index febdab99..a395e4bb 100644
--- a/packages/typedoc-plugin-markdown/test/specs/urls.spec.ts
+++ b/packages/typedoc-plugin-markdown/test/specs/urls.spec.ts
@@ -35,4 +35,8 @@ describe(`Urls`, () => {
   test(`should gets Urls for documents single module`, () => {
     expectUrlsToEqual('documentsSingleModule', ['members', 'modules']);
   });
+
+  test(`should gets Urls with media assets`, () => {
+    expectUrlsToEqual('comments', ['members']);
+  });
 });
diff --git a/packages/typedoc-plugin-markdown/test/specs/utils.spec.ts b/packages/typedoc-plugin-markdown/test/specs/utils.spec.ts
index 6bfd044e..ea8c4e72 100644
--- a/packages/typedoc-plugin-markdown/test/specs/utils.spec.ts
+++ b/packages/typedoc-plugin-markdown/test/specs/utils.spec.ts
@@ -10,6 +10,6 @@ describe(`Utils`, () => {
   });
 
   test(`should get variable with brackets`, () => {
-    expectFileToEqual('utils', 'members', 'variables/VariableWithChars.md');
+    expectFileToEqual('utils', 'members', 'variables/variableWithChars.md');
   });
 });
diff --git a/packages/typedoc-vitepress-theme/CHANGELOG.md b/packages/typedoc-vitepress-theme/CHANGELOG.md
index e1e5c9f8..9c6d0db7 100644
--- a/packages/typedoc-vitepress-theme/CHANGELOG.md
+++ b/packages/typedoc-vitepress-theme/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Changelog
 
-## 1.0.1
+## 1.0.1 (2024-07-02)
 
 ### Patch Changes