diff --git a/.changeset/large-lemons-hammer.md b/.changeset/large-lemons-hammer.md
index 3843e244b..7e59f97cc 100644
--- a/.changeset/large-lemons-hammer.md
+++ b/.changeset/large-lemons-hammer.md
@@ -3,3 +3,4 @@
---
- Remove superfluous newlines from table column descriptions (#591).
+- Handle multiple `@example` tags on same reflection.
diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts
index 9a1e42b71..fac6e611a 100644
--- a/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts
+++ b/packages/typedoc-plugin-markdown/src/theme/resources/partials/comments.comment.ts
@@ -2,7 +2,7 @@ import { bold, heading } from '@plugin/libs/markdown';
import { camelToTitleCase, formatTableColumn } from '@plugin/libs/utils';
import { sanitizeComments } from '@plugin/libs/utils/sanitize-comments';
import { MarkdownThemeContext } from '@plugin/theme';
-import { Comment } from 'typedoc';
+import { Comment, CommentTag } from 'typedoc';
/**
* @category Comment Partials
@@ -32,7 +32,32 @@ export function comment(
}
if (opts.showTags && model.blockTags?.length) {
- const tags = model.blockTags
+ const blockTags = model.blockTags.reduce(
+ (previous: CommentTag[], current: CommentTag) => {
+ if (current.tag === '@example') {
+ const prevExampleTag = previous.find((tag) =>
+ ['@example', '@examples'].includes(tag.tag),
+ );
+ if (prevExampleTag) {
+ return previous.map((prevTag) => {
+ if (prevTag === prevExampleTag) {
+ current.content.unshift({ kind: 'text', text: '\n\n' });
+ return {
+ ...prevTag,
+ tag: '@examples',
+ content: [...prevTag.content, ...current.content],
+ };
+ }
+ return prevTag;
+ });
+ }
+ }
+ return [...previous, current];
+ },
+ [],
+ );
+
+ const tags = blockTags
.filter((tag) => tag.tag !== '@returns')
.filter(
(tag) =>
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 2502a66c6..02d5116a6 100644
--- a/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts
+++ b/packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts
@@ -103,3 +103,40 @@ export const SameName = true;
export const prop = true;
export const propb = true;
export const _prop_with_underscore = true;
+
+/**
+ * Function with multiple example tags
+ *
+ * @example
+ * // If there are no code blocks, TypeDoc assumes the whole tag
+ * // should be a code block. This is not valid TSDoc, but is recognized
+ * // by VSCode and enables better JSDoc support.
+ *
+ * factorial(1)
+ *
+ * @example
+ * If there is a code block, then both TypeDoc and VSCode will treat
+ * text outside of the code block as regular text.
+ *
+ * ```ts
+ * factorial(1)
+ * ```
+ */
+export function multipleExampleTags() {
+ return true;
+}
+
+/**
+ * Function with single example tag
+ *
+ * @example
+ * If there is a code block, then both TypeDoc and VSCode will treat
+ * text outside of the code block as regular text.
+ *
+ * ```ts
+ * factorial(1)
+ * ```
+ */
+export function singleExampleTag() {
+ return true;
+}
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/interfaces.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/interfaces.ts
index 24969b441..056fbde57 100644
--- a/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/interfaces.ts
+++ b/packages/typedoc-plugin-markdown/test/fixtures/src/reflections/interfaces.ts
@@ -16,7 +16,7 @@ export interface BasicInterface {
/**
* @deprecated
*
- * This prop is deprecte
+ * This prop is deprecated
*
* @someTag
*
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 279954e82..011e9ba5a 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
@@ -92,6 +92,11 @@ This is a simple example on how to use include.
- [\\_prop\\_with\\_underscore](variables/prop_with_underscore.md)
- [prop](variables/prop.md)
- [propb](variables/propb.md)
+
+## Functions
+
+- [multipleExampleTags](functions/multipleExampleTags.md)
+- [singleExampleTag](functions/singleExampleTag.md)
"
`;
@@ -187,6 +192,11 @@ This is a simple example on how to use include.
- [\\_prop\\_with\\_underscore](/some-path/variables/prop_with_underscore.mdx)
- [prop](/some-path/variables/prop.mdx)
- [propb](/some-path/variables/propb.mdx)
+
+## Functions
+
+- [multipleExampleTags](/some-path/functions/multipleExampleTags.mdx)
+- [singleExampleTag](/some-path/functions/singleExampleTag.mdx)
"
`;
@@ -342,6 +352,56 @@ This is a simple example on how to use include.
### propb
> \`const\` **propb**: \`true\` = \`true\`
+
+## Functions
+
+### multipleExampleTags()
+
+> **multipleExampleTags**(): \`boolean\`
+
+Function with multiple example tags
+
+#### Returns
+
+\`boolean\`
+
+#### Examples
+
+\`\`\`ts
+// If there are no code blocks, TypeDoc assumes the whole tag
+// should be a code block. This is not valid TSDoc, but is recognized
+// by VSCode and enables better JSDoc support.
+
+factorial(1)
+\`\`\`
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
+
+***
+
+### singleExampleTag()
+
+> **singleExampleTag**(): \`boolean\`
+
+Function with single example tag
+
+#### Returns
+
+\`boolean\`
+
+#### Example
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
"
`;
@@ -513,5 +573,59 @@ This is a simple example on how to use include.
### propb
> \`const\` **propb**: \`true\` = \`true\`
+
+## Functions
+
+
+
+### multipleExampleTags()
+
+> **multipleExampleTags**(): \`boolean\`
+
+Function with multiple example tags
+
+#### Returns
+
+\`boolean\`
+
+#### Examples
+
+\`\`\`ts
+// If there are no code blocks, TypeDoc assumes the whole tag
+// should be a code block. This is not valid TSDoc, but is recognized
+// by VSCode and enables better JSDoc support.
+
+factorial(1)
+\`\`\`
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
+
+***
+
+
+
+### singleExampleTag()
+
+> **singleExampleTag**(): \`boolean\`
+
+Function with single example tag
+
+#### Returns
+
+\`boolean\`
+
+#### Example
+
+If there is a code block, then both TypeDoc and VSCode will treat
+text outside of the code block as regular text.
+
+\`\`\`ts
+factorial(1)
+\`\`\`
"
`;
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap
index 87de673dd..858ba0882 100644
--- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap
+++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/objects-and-params.spec.ts.snap
@@ -17,7 +17,7 @@ Comments for BasicInterface
#### Deprecated
-This prop is deprecte
+This prop is deprecated
#### Some Tag
@@ -204,7 +204,7 @@ Comments for BasicInterface
| Property | Type | Description |
| :------ | :------ | :------ |
-| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecte
**Some Tag**
Comments for some tag |
+| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecated
**Some Tag**
Comments for some tag |
| \`functionProp\` | (\`s\`: \`string\`) => \`boolean\` | Comments for functionProper |
| \`optionalProp?\` | \`string\` | Comments for optional prop |
| \`prop\` | \`string\` | Comments for prop |
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap
index 9837f2d6a..729433f3f 100644
--- a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap
+++ b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap
@@ -17,7 +17,7 @@ Comments for BasicInterface
#### Deprecated
-This prop is deprecte
+This prop is deprecated
#### Some Tag
@@ -244,7 +244,7 @@ Comments for BasicInterface
| Property | Type | Description |
| :------ | :------ | :------ |
-| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecte
**Some Tag**
Comments for some tag |
+| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecated
**Some Tag**
Comments for some tag |
| \`functionProp\` | (\`s\`: \`string\`) => \`boolean\` | Comments for functionProper |
| \`optionalProp?\` | \`string\` | Comments for optional prop |
| \`prop\` | \`string\` | Comments for prop |
@@ -282,7 +282,7 @@ Comments for ExtendedInterface
#### Deprecated
-This prop is deprecte
+This prop is deprecated
#### Some Tag
@@ -559,7 +559,7 @@ Comments for ExtendedInterface
| Property | Type | Description | Inherited from |
| :------ | :------ | :------ | :------ |
-| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecte
**Some Tag**
Comments for some tag | [\`BasicInterface\`](BasicInterface.md).\`deprecatedProp\` |
+| ~~\`deprecatedProp\`~~ | \`string\` | **Deprecated**
This prop is deprecated
**Some Tag**
Comments for some tag | [\`BasicInterface\`](BasicInterface.md).\`deprecatedProp\` |
| \`extendedProp\` | \`string\` | - | - |
| \`functionProp\` | (\`s\`: \`string\`) => \`boolean\` | Comments for functionProper | [\`BasicInterface\`](BasicInterface.md).\`functionProp\` |
| \`optionalProp?\` | \`string\` | Comments for optional prop | [\`BasicInterface\`](BasicInterface.md).\`optionalProp\` |