Github user mattf-horton commented on the issue:
https://github.com/apache/metron/pull/530
@ottobackwards , in general (a) make it work in github, and (b) make sure
the human-readable link reference text is the same as the human-readable anchor
text. That way the site-book generator will be able to derive the site-book
link text.
The trick is the generated tag text. As noted in the fix-md-dialect.py
script:
```
The problem with generated tags is that Github-MD forces header text to
lower-case, and
replaces blank spaces with hyphens, while doxia-markdown leaves case
unchanged, and replaces
blanks with underscores. Fortunately we seem to have a culture of using
link references that
are typographically the same as the header text, so we have some basis for
fixing most links.
```
So for example, if you want to link to an h2 header "This Is Great" in file
Mega.md, your Github-MD link tag will be "\<relative
path\>/Mega.md#this-is-great", BUT the human-readable link text must also be
"This Is Great", so that during site built we can magically generate the Doxia
html link tag of "\<relative path\>/Mega.html#This_Is_Great".
This is only for auto-generated tags for headers and such. If you are
using hand-crafted html markup, with explicitly named tags, then you don't need
to worry. Use whatever link reference and anchor text you want, and the tag
you defined. If the link reference text doesn't look like the tag, then it
won't try to auto-convert. That would be the conditional at
https://github.com/apache/metron/blob/master/site-book/bin/fix-md-dialect.py#L246-L247
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
