Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: TypeDoc 0.23 compatibility fixes
- Loading branch information
Showing
22 changed files
with
119 additions
and
276 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
158 changes: 38 additions & 120 deletions
158
packages/typedoc-plugin-markdown/src/resources/helpers/comment.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,130 +1,48 @@ | ||
import * as Handlebars from 'handlebars'; | ||
import { CommentDisplayPart } from 'typedoc/dist/lib/models/comments/comment'; | ||
import { MarkdownTheme } from '../../theme'; | ||
import * as path from 'path'; | ||
import * as fs from 'fs'; | ||
import { Reflection } from 'typedoc'; | ||
|
||
const URL_PREFIX = /^(http|ftp)s?:\/\//; | ||
const BRACKETS = /\[\[([^\]]+)\]\]/g; | ||
const INLINE_TAG = | ||
/(?:\[(.+?)\])?\{@(link|linkcode|linkplain)\s+((?:.|\n)+?)\}/gi; | ||
const INCLUDE_PATTERN = /\[\[include:([^\]]+?)\]\]/g; | ||
const MEDIA_PATTERN = /media:\/\/([^ "\)\]\}]+)/g; | ||
|
||
export default function (theme: MarkdownTheme) { | ||
Handlebars.registerHelper('comment', function (this: string) { | ||
const { project, reflection, includes, mediaDirectory } = theme; | ||
|
||
function replaceBrackets(text: string) { | ||
return text.replace( | ||
BRACKETS, | ||
(match: string, content: string): string => { | ||
const split = splitLinkText(content); | ||
return buildLink(match, split.target, split.caption); | ||
}, | ||
); | ||
} | ||
|
||
function replaceInlineTags(text: string): string { | ||
return text.replace( | ||
INLINE_TAG, | ||
(match: string, leading: string, tagName: string, content: string) => { | ||
const split = splitLinkText(content); | ||
const target = split.target; | ||
const caption = leading || split.caption; | ||
|
||
return buildLink(match, target, caption, tagName === 'linkcode'); | ||
}, | ||
); | ||
} | ||
|
||
function buildLink( | ||
original: string, | ||
target: string, | ||
caption: string, | ||
monospace = false, | ||
) { | ||
if (monospace) { | ||
caption = '`' + caption + '`'; | ||
} | ||
|
||
if (URL_PREFIX.test(target)) { | ||
return `[${caption}](${target})`; | ||
} | ||
|
||
let targetReflection: Reflection | undefined; | ||
if (reflection) { | ||
targetReflection = reflection.findReflectionByName(target); | ||
} else if (project) { | ||
targetReflection = project.findReflectionByName(target); | ||
} | ||
|
||
if (targetReflection && targetReflection.url) { | ||
return `[${caption}](${Handlebars.helpers.relativeURL( | ||
targetReflection.url, | ||
)})`; | ||
} else { | ||
return original; | ||
} | ||
} | ||
|
||
function splitLinkText(text: string) { | ||
let splitIndex = text.indexOf('|'); | ||
if (splitIndex === -1) { | ||
splitIndex = text.search(/\s/); | ||
} | ||
if (splitIndex !== -1) { | ||
return { | ||
caption: text | ||
.substr(splitIndex + 1) | ||
.replace(/\n+/, ' ') | ||
.trim(), | ||
target: text.substr(0, splitIndex).trim(), | ||
}; | ||
} else { | ||
return { | ||
caption: text, | ||
target: text, | ||
}; | ||
} | ||
} | ||
|
||
let text = this; | ||
const context = Object.assign(text, ''); | ||
|
||
if (includes) { | ||
text = text.replace( | ||
INCLUDE_PATTERN, | ||
(match: string, includesPath: string) => { | ||
includesPath = path.join(includes!, includesPath.trim()); | ||
if ( | ||
fs.existsSync(includesPath) && | ||
fs.statSync(includesPath).isFile() | ||
) { | ||
const contents = fs.readFileSync(includesPath, 'utf-8'); | ||
if (includesPath.substr(-4).toLocaleLowerCase() === '.hbs') { | ||
const template = Handlebars.compile(contents); | ||
return template(context); | ||
} else { | ||
return contents; | ||
Handlebars.registerHelper('comment', function (parts: CommentDisplayPart[]) { | ||
const result: string[] = []; | ||
for (const part of parts) { | ||
switch (part.kind) { | ||
case 'text': | ||
case 'code': | ||
result.push(part.text); | ||
break; | ||
case 'inline-tag': | ||
switch (part.tag) { | ||
case '@label': | ||
case '@inheritdoc': | ||
break; | ||
case '@link': | ||
case '@linkcode': | ||
case '@linkplain': { | ||
if (part.target) { | ||
const url = | ||
typeof part.target === 'string' | ||
? part.target | ||
: Handlebars.helpers.relativeURL(part.target.url); | ||
const wrap = part.tag === '@linkcode' ? '`' : ''; | ||
result.push( | ||
url ? `[${wrap}${part.text}${wrap}](${url})` : part.text, | ||
); | ||
} else { | ||
result.push(part.text); | ||
} | ||
break; | ||
} | ||
} else { | ||
return ''; | ||
default: | ||
result.push(`{${part.tag} ${part.text}}`); | ||
break; | ||
} | ||
}, | ||
); | ||
} | ||
|
||
if (mediaDirectory) { | ||
text = text.replace(MEDIA_PATTERN, (match: string, mediaPath: string) => { | ||
if (fs.existsSync(path.join(mediaDirectory!, mediaPath))) { | ||
return Handlebars.helpers.relativeURL('media') + '/' + mediaPath; | ||
} else { | ||
return match; | ||
} | ||
}); | ||
break; | ||
default: | ||
result.push(''); | ||
} | ||
} | ||
|
||
return replaceInlineTags(replaceBrackets(text)); | ||
return result.join(''); | ||
}); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
17 changes: 17 additions & 0 deletions
17
packages/typedoc-plugin-markdown/src/resources/helpers/returns.ts
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
import * as Handlebars from 'handlebars'; | ||
import { Comment } from 'typedoc'; | ||
|
||
export default function () { | ||
Handlebars.registerHelper('returns', function (comment: Comment) { | ||
const md: string[] = []; | ||
|
||
if (comment.blockTags?.length) { | ||
const tags = comment.blockTags | ||
.filter((tag) => tag.tag === '@returns') | ||
.map((tag) => Handlebars.helpers.comment(tag.content)); | ||
md.push(tags.join('\n\n')); | ||
} | ||
|
||
return md.join(''); | ||
}); | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,7 +2,7 @@ | |
|
||
{{#if hasVisibleComponent}} | ||
|
||
{{{comments}}} | ||
{{{comments this}}} | ||
|
||
{{/if}} | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -2,6 +2,6 @@ | |
|
||
{{#with model.readme}} | ||
|
||
{{{comment}}} | ||
{{{comment this}}} | ||
|
||
{{/with}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.