Render links to other documents properly without "file:" syntax in some markup languages

[skalee]

Yard supports cross reference links to other textual documents via {file:<path-to-file>} syntax. However, this Yard's flavour is not portable. Such syntax works great in Yard, but nowhere else, e.g. on GitHub.

Yard's own README.md is a great example. Following piece of Markdown code produces broken (unparsed) output in GitHub, and probably in other Markdown renderers:

## Changelog

See {file:CHANGELOG.md} for a list of changes.

With https://github.com/lsegal/yard/issues/181#issuecomment-444372 in mind, I don't think that it can be fixed properly for Markdown as it doesn't support inter-document references, just plain relative links.

However, AsciiDoc is a different story. It features inter-document cross references explicitly, see:

• https://asciidoctor.org/docs/asciidoc-writers-guide/#cross-references
• https://asciidoctor.org/docs/user-manual/#navigating-between-source-files

IMHO that makes Yard's {{file:…}} syntax redundant in context of AsciiDoc. If only Yard would render AsciiDoc's cross references properly, one could create documents which are displayed correctly in Yard, GitHub and everywhere else.

I am not sure about Textile and others. Perhaps they feature cross references as well.

[lsegal]

IMHO that makes Yard's {{file:…}} syntax redundant in context of AsciiDoc.

This isn't entirely accurate, and there's a bit more to unpack here, but I'll talk about the more pertinent one:

AsciiDoc cross references are less likely to be correctly linked across different backends when rendering YARD templates. For example, the default/html YARD template might put extra files in a specific root directory, but another template might not do this. When using {file:...} linking format, YARD is able to correctly identify the link location based on the active output serializer, whereas AsciiDoc is making educated guesses based on relative links.

It's certainly true that AsciiDoc has more powerful features and better integration with GitHub, but it's also important to realize that YARD syntax works alongside those features, not in replacement of, so if you really want to use adoc formatting for all your links, you should be able to do this, but you will lose portability on the YARD side. These are tradeoffs that users can decide to make rather than YARD making these decisions for you.

One thing that YARD could do better is augment markdown, adoc, and other syntaxes to gracefully replace links in those native markups, but YARD does not parse markup formats by design so that it doesn't need to know how markdown or asciidoc works in order to render it. Because all the rendering is piped externally, it also means that it's harder to provide these types of integrations, i.e., converting an AsciiDoc xref into a YARD object ref.

[esotericpig]

I made a gem with a rake task that will gsub this text in the generated doc/index.html (and doc/file.README.html).

https://github.com/esotericpig/yard_ghurt

You can see how I use it in my Rakefile:

https://github.com/esotericpig/yard_ghurt/blob/master/Rakefile

This will replace any local file links to their file.{filename}.html equivalent, and it will fix anchor links (relative links), so it will work on GitHub and with YARD:

https://esotericpig.github.io/docs/yard_ghurt/yardoc/index.html

This doesn't parse the HTML with a DOM or SAX parser or anything complicated. It just finds & replaces text in the file. You can see the actual code here.

However, because this is an additional rake task, your gem on RubyDoc.info will still be "broken," but I don't think this is such a big deal because you can use GitHub Pages to host your docs (like I do) for free.

This isn't a solution to the core, but it's a plugin (or hack lol).