Relative README links do not redirect

[ghost]

Hey there!

Relative links redirecting to a certain section in markdown are non-functional. They’re not working in the readme.html. After the build, they are not clickable anymore in the output HTML files.

Example:

[Text](#Example)

Cheers.

[onury]

That's a bookmark (on the same page) in your example. How is that not clickable?

Pls see this item in the F.A.Q.

[ghost]

@onury, I am not indicating to the source files or the JSDoc comments here. The obstacle is Docma lowercases the name of the heading or section and adds it as a new heading's ID. Additionally, you can test this behavior here.

For instance, here's a markdown file (README.md):

[Text](#MySection)

# My Section
Text here

The above markdown file will be parsed by Docma as:

<a href="#MySection">Text</a>

<h1 id="mysection">My Section</h1>

[onury]

I see.

That behavior is intentional. In order to use URL-safe characters, Docma removes .,;'" and back-tick characters, and replaces any character other than a-z0-9$_ with -. Then converts it to lower-case.

So in your example, heading id for My Section will be parsed as my-section and should be linked as #my-section.

GitHub also has a similar behavior so Docma also does this so that you can use the same markdown file both on GitHub and your generated documentation. In other words, your [Text](#MySection) will not work on GitHub and similar sites. For your own example, see how your markdown ids and bookmarks are parsed on GitHub: https://github.com/chroventer/endb#third-party-adapters « notice the bookmark lowercased.

Uppercase seems to be supported as well on GitHub. That I'll consider. There is no special characters in your example but GitHub removes them so we do as well.

Note: Maybe this behavior is not clearly documented. I'll look into that.