Closed lorenzolewis closed 3 months ago
Thanks for this. Have released another version typedoc-plugin-markdown@4.0.0-next.20 that iincludes:
namedAchors
is true)--namedAnchors
is true html anchors will be included in the table row as per your example (only for properties at the moment but will look to do the same for params too).My only feedback on this right now is that --namedAnchors
will also force anchors on headings where some doc build tools will already put this in place. This can unintentional impacts with the addition of another <a>
tag (such as whitespace being added, non-unique IDs due to generation conflicts, etc.).
I wonder if this makes sense to only apply anchors to things (i.e. content in tables) that otherwise couldn't be easily applied with remark/rehype plugins (in the case of headings it would be https://github.com/rehypejs/rehype-slug)?
I've also see aria-hidden="true" tabindex="-1"
being applied to the <a>
tag to improve a11y (you can see this being the case in rehype-autolink-headings https://github.com/rehypejs/rehype-autolink-headings#use)
Otherwise this works perfectly for what I had in mind for properties. If the way you've currently implemented this for properties is how you'd like it done objects generated by --propertiesFormat, --enumMembersFormat, and --typeDeclarationFormat then I'd be happy to make a PR to implement those based on that.
Yeah good points. The initial requirement for namedAnchors
is that Bitbucket server was not applying anchors at all https://github.com/tgreyuk/typedoc-plugin-markdown/issues/74. Not sure if this is still the case, but even so for this type of use case it might still be useful to continue to support anchors on headings without parsing with rehype. Perhaps namedAnchors
should support context e.g ['headers','tables']
or split out into seperate options. Not too sure. I initially didn't want to support any HTML in the output and was going to drop this option completely, but I don't think there is another solution specifically for referencing symbols in tables.
If the way you've currently implemented this for properties is how you'd like it done objects generated by https://github.com/tgreyuk/typedoc-plugin-markdown/issues/463#--propertiesformat, https://github.com/tgreyuk/typedoc-plugin-markdown/issues/463#--enummembersformat, and https://github.com/tgreyuk/typedoc-plugin-markdown/issues/463#--typedeclarationformat then I'd be happy to make a PR to implement those based on that.
Sure - if you are happy to work your way though the code :). The tests are disabled at the moment due to some breaking changes in 0.25 but will revisit them shortly.
I might need to give that one a bit of a wait then. I remember last time the tests were really helpful to me when developing so if possible I'd rather have them for my own sanity 😅
I'm going to be out on vacation for a chunk of time but if this isn't in by then I'd be happy to contribute once I'm back.
typedoc-plugin-markdown@4.0.0
https://www.typedoc-plugin-markdown.org/docs/options#usehtmlanchors
When referring to some items using
{@ link }
syntax it can result in broken links when using a table format and referencing an object in that table. This so far seems applicable to:And any others that might be given an option to render as a table. I've gotten around this previously by using a
<a>
tab with anid
andname
attribute: https://github.com/tauri-apps/tauri-docs/blob/3cf2a86b43e5263e3b30c337ee8a9fd508882e9e/patches/typedoc-plugin-markdown%404.0.0-next.17.patch#L9.However, it seems that https://typedoc.org/api/classes/Models.DeclarationReflection.html#anchor is no longer returning a value for these in the last couple of versions. I'm happy to PR this if you agree and let me know how the IDs should be generated/read from.