I've written some using documentation for a ruby gem. I'm using yard to generate the ruby gem reference documentation from the ruby source, and I want yard to work with this other markdown documentation.
I've written the documentation within the gitlab wiki which uses the same markdown as github and all the links to anchors work.
When I use yard to generate html from the markup two things go wrong. The first is the links didn't work because in the markdown references to other files didn't include an extension e.g. [Getting Started] (Introduction#getting-started) which worked in the wiki but yard needs a [Getting Started] (Introduction.html#getting-started). I was able to get around this by writing a rewrite rule in the .htaccess file.
The second issue is harder. The wiki generated anchors to headings are like as above, whereas yard anchors are: Introduction.html#Getting_Started
I've tried sorting out the case issue by adding [NC] in the .htaccess file but this didn't help. Plus there is the issue of the "-" changing to a "_".
The relevant bits from my .yardopts file in relation to my question are:
--markup markdown
--markup-provider redcarpet
My question is:
Is the structure of the generated anchors due to either the choice of markup or markup provider? I'm confused by these terms and I've not been able to find useful documentation about them.
I've got the github-markup gem installed and I've tried replacing markdown with github-markup, and that didn't work, then I tried replace redcarpet with github-markup but that also doesn't work.
I keep searching for documentation to try and understand what I'm doing here without gaining any clarity thus the clutching at straws.