Feature Request: auto links to external documentation

[SilentSin]

It would be awesome if my documentation could automatically create links to external documentation just like it does to the pages generated for my API. For example, in a Unity project when I write GameObject in a markdown file I'd like it to link to https://docs.unity3d.com/ScriptReference/GameObject.html.

This could have two parts:

• First you'd specify "here's a website to check for documentation". Or maybe "if the class is in this DLL, check this website".
• Then it would likely also be good to have the ability to manually specify specific pages. So that Animation Events could link to https://docs.unity3d.com/Manual/animeditor-AnimationEvents.html without needing to put that link in everywhere.

Maybe it could use a "LinkResolver" text file that specifies the exact token -> URL pairings so it doesn't need to ping the target website every time to make sure it exists, it just writes into that file the first time. And so you can manually specify and alter the links in one central location.

This might be something that could be done with a custom pipeline (or module?), but I have no idea how to take the regular default pipeline and insert an extra step for modifying the output generated by code tags.

[daveaglick]

Another cool idea. The AutoLink module that the docs recipe uses essentially does just take a dictionary of tokens to URLs, so adding functionality to specify additional manual pairings either from a text file or in the config file shouldn’t be too tough.

The thought about automatically identifying new link pairs (for example, from other documentation sites) sounds neat, but implementation of that seems like it could get complicated. Not all docs follow the same pattern, so we’d need a way to say “here’s how you can crawl the site for symbols (or pages) that could be linked to”.

You also mentioned maybe using a library to extract the candidate symbols - then we’d just need to define a pattern for the external URLs. For example, “for any symbol in the library Foo.Bar, link to https://foobar.org/%namespace%/%symbol%”. Or maybe even just use a delegate in the config file that takes the symbol and returns a link. We could even define a default set for CoreFx symbols to link to MS docs.

The one bit of this I’m not too sure about is auto-linking arbitrary phrases like Animation Events. I’d be concerned these could get overly general and we’d end up linking unintended phrases.

[SilentSin]

The one bit of this I’m not too sure about is auto-linking arbitrary phrases like Animation Events. I’d be concerned these could get overly general and we’d end up linking unintended phrases.

I've also noticed a couple of places where something has been auto-linked to the only viable candidate in my API, but it doesn't actually fit the context I was using the word in. I could manually specify a different link, but is there a simple way to just tell it not to auto link a particular word as part of the markdown?

[SilentSin]

Is it possible to access the auto-link dictionary within the config.wyam file to manually add some specific pairs?

I can see pages for the AutoLink Module and AutoLink Class, but I've never used any pipeline customisations before so I don't know what's possible there.

And if it is possible, can I modify the dictionary it already uses rather than needing to run the module a second time on every file with my own dictionary?