Headers for generic types

[aremes]

I have searched open and closed issues as well as the documentation. I hope i have not missed something. If so, sorry for the inconvenience and i would love it if you could point me in the right direction as to what it is i'm doing wrong.

Somehow, when a class implements a generic interface, the links just end in a '<' I've attached a zip file containing a small project including its generated .md file that shows this issue DefaultDocumentationTestWithGenerics.zip

It seems to affect almost all occurrences of generics in headers (see how it displays the method returning a "Task\<string>"

Is this by design? Can this be fixed by configuration?

[aremes]

Nevermind, this issue has nothing to do with this Project, it turned out to be in my MD renderer Sorry!

[Doraku]

No worries, normally it should handle generic correctly (that was my main issue with existing documentation generation tool which made me start this project haha) but I think there could be some display error if you do not add the type parameter xml documentation in your code.

[aremes]

For anyone else stumbling upon this, i've opened up an issue with the real culprit https://github.com/mkdocs/mkdocs/issues/2847. @Doraku I have all the type parameters configured properly. Thanks for the fast response anyways!

Is there any simple way to tell DefaultDocumentation not to add the "title" properties to links (as in the quoted second part within the parantheses of [text](link "title")?

edit: If i'm not mistaken, the "title" gets set here so to answer my question: no :(

[Doraku]

yeah sorry :/ it's causing some problem for you?

[aremes]

So here's the background: I'm generating Markdown files from a pretty big solution with a lot of projects, then using MkDocs to host/render it.

MkDocs seems to use a Markdown-interpreter that does strange things with backticks in Link titles. So whenever a class implements a generic interface, the output is broken. The chances of changing MkDocs behavior in that regard are very slim, so i'm thinking: removing the link titles (since they're not really useful to me anyways) would solve the problem. I'm currently looking into writing a Plugin to do that. That should be possible, right?

[Doraku]

hum, that should be possible but you would have to rewrite every section since the AppendUrl method is an extension method used everywhere in the markdown section implementations so it's not a really good solution. I didn't want to add any more extra markdown configuration but maybe I'll just do that, it's relativement simple compared to what you would have to do >_>

[aremes]

I understand your hesitation to add more configuration. And this is really somewhat of a unicorn-issue, so i question wether it makes sense to put that much effort into it. What I am wondering, though is: If i understand https://github.com/Doraku/DefaultDocumentation/issues/104 correctly, relative URLs are hard to implement in a plug-in for the exact same reason (necessity to hook into extension-method), right? maybe this issue and #104 have a common solution? (Preferably one that allows you to be more lazy ;) )

[Doraku]

no sure if this is the way to go for both those issues, I added a cheap way to "override" the implementation of the AppendUrl (to remove tooltip) and AppendLink (to write relative url for folders). It works by creating a ISection whose only goal is to setup the overrides https://github.com/Doraku/DefaultDocumentation/blob/3149b892e745684b4c0c720eee68d09b2788050f/source/Sample/DefaultDocumentation.PluginExample/FolderFileNameOverrides.cs#L39 and then you need to use this section first in your configuration https://github.com/Doraku/DefaultDocumentation/blob/3149b892e745684b4c0c720eee68d09b2788050f/source/DefaultDocumentation.Api/DefaultDocumentation.json#L13 It kinda looks like a plugin of a plugin hack, not sure if something is missing in the main api for those cases or if it should be left at the discretion of plugin developers (and sadly for me DefaultDocumentation.Markdown is one haha).

[aremes]

Interesting solution indeed! As you said, it does seem a bit hacky, but i currently have no better solution.. 😊

[juliansangillo]

I am running into issues rendering generics as well. However, my issue is that the renderer removes the <> and everything in between them.

MyClass<T>

is rendered as

MyClass

I don't think this is an actual bug with the renderers as all the ones I use do this (JetBrains Rider, GitHub, and GitBook). When I write markdown manually, I often have to escape the < or replace the braces with < and > respectively.

Is there some way we can do that either in DefaultDocumentation or in a plugin?

It seems like it does this with link text already. Just not the headers.

| Classes | |
| :--- | :--- |
| [AssemblyCollection<TEntryPoint>](...)

[juliansangillo]

I am running into issues rendering generics as well. However, my issue is that the renderer removes the <> and everything in between them.

MyClass<T>

is rendered as

MyClass

I don't think this is an actual bug with the renderers as all the ones I use do this (JetBrains Rider, GitHub, and GitBook). When I write markdown manually, I often have to escape the < or replace the braces with < and > respectively.

Is there some way we can do that either in DefaultDocumentation or in a plugin?

It seems like it does this with link text already. Just not the headers.

| Classes | |
| :--- | :--- |
| [AssemblyCollection<TEntryPoint>](...)

[adlerzei]

Hi, the changes that make AppendUrl accessible in the API are still in a feature branch. Are you planning to release this? It would be very helpful for my case.