Is it possible to write Markdown links in a way that satisfies both Github and Doxygen?

Question

My project's current directory structure is <ProjectRooot>/wiki, and there are three Markdown files within the wiki directory.

One of them links to the other two, and I have tried two ways of writing the links.

First Way

[Kernel API & Core Negotiation Protocol](wiki/KernelAPI.md)
[Priorities & Starvation](wiki/Priorities.md)

Second Way

[Kernel API & Core Negotiation Protocol](KernelAPI.md)
[Priorities & Starvation](Priorities.md)

Under the first way, the links work correctly in the generated Doxygen and are broken when accessed on github.com. Under the second way, the links work correctly on github.com, but Doxygen does not even try to link at all.

Is there a way to write the links that will satisfy both?

Have you tried absolute URLs? In other words, have the URL paths start form the root: `/wiki/KernelAPI.md`. Notice the slash at the beginning. It may not work, but I'd at least try it. — Waylan, Jan 06 '17 at 00:25

score 0 · Answer 1 · edited May 23 '17 at 12:16

0

Is there a way to write the links that will satisfy both?

No, but you could:

write it so it works on GitHub (GFM: GitHub Flavored Markdown)
setup a local content filter driver (smudge script in a .gitattributes file) which will, on git checkout, transform those links into ones compatible with Doxygen.

^{(image from "Customizing Git - Git Attributes", from "Pro Git book")}

edited May 23 '17 at 12:16

Community

1
1

answered Jan 05 '17 at 05:33

VonC

1,262,500
529
4,410
5,250

I will try this. I assume git diff should show no difference if this is written correctly? – merlin2011 Jan 06 '17 at 00:36
@merlin2011 yes, if you write the clean script which restore the original content. – VonC Jan 06 '17 at 05:11
I did this and it works on `localhost`, but I am collaborating with others and it looks like it takes an [additional hack](http://stackoverflow.com/questions/26125573/gitattributes-smudge-and-clean-filters-as-a-part-of-the-repository) which needs a fresh clone to make this work for everyone else as well (rather than just requiring them to pull the repo). Thus, I will probably not use this solution because if one person tries to generate docs without a correct implementation, links in Doxygen will break. Thanks for teaching me about this though! – merlin2011 Jan 12 '17 at 08:54
@merlin2011 yes, a content filter driver needs to be activated (once) locally – VonC Jan 12 '17 at 08:55

Is it possible to write Markdown links in a way that satisfies both Github and Doxygen?

First Way

Second Way

1 Answers1