Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Not all headers are automatically linked #367

Closed
LPGhatguy opened this issue Mar 16, 2015 · 5 comments
Closed

Not all headers are automatically linked #367

LPGhatguy opened this issue Mar 16, 2015 · 5 comments
Labels
Bug
Milestone

Comments

@LPGhatguy
Copy link

@LPGhatguy LPGhatguy commented Mar 16, 2015

I have an API reference site for a project that's hosted on ReadTheDocs using mkdocs as the documentation engine. Headers that contain things like <code> blocks aren't linked, while all others seem to be.

I can reproduce this locally with a plain mkdocs install using the RTD theme.

Here's an example:
http://carbon.lpghatguy.com/en/latest/Classes/Collections.Tuple/

All three of the methods in that page should be automatically linked in the sidebar navigation, but only the one without any fancy decoration is. All of them have been given valid HTML ids, so they're possible to link, they just aren't.

The markdown for that page, which works around a couple RTD bugs and doesn't look that great, is here:
https://raw.githubusercontent.com/lua-carbon/carbon/master/docs/Classes/Collections.Tuple.md

@d0ugal d0ugal added the Bug label Mar 17, 2015
@d0ugal
Copy link
Member

@d0ugal d0ugal commented Mar 17, 2015

I think I've seen this before and I think it happens when a page doesn't contain a top level # title as yours doesn't - you add it with HTML directly.

I can't explain why it chooses the titles it does, that is strange.

@d0ugal
Copy link
Member

@d0ugal d0ugal commented Apr 2, 2015

Just having a look at this - I think you managed to work around the problem? The current link looks great.

If this still needs looking into, can you comment with a link to a problem area or provide some markdown with the issue. Thanks.

@d0ugal d0ugal closed this Apr 2, 2015
@LPGhatguy
Copy link
Author

@LPGhatguy LPGhatguy commented Apr 3, 2015

I ended up just redoing the entire website using HTML links instead; this way, nothing gets linked at all, but I needed it for other requirements.

However, it's still possible to reproduce:

# Hello World (linked)
# Hello <code>World</code> (unlinked)
@d0ugal
Copy link
Member

@d0ugal d0ugal commented Apr 3, 2015

Thanks - I've got a failing test case. The problem is using regular expressions to parse HTML which is never a good idea. Working on a fix.

@d0ugal d0ugal added this to the 0.12.0 milestone Apr 3, 2015
d0ugal added a commit to d0ugal/mkdocs that referenced this issue Apr 3, 2015
We now use HTMLParser rather than regular expressions which makes it
much smarter about handling tags within the titles themselves.

Fixes mkdocs#367
@d0ugal
Copy link
Member

@d0ugal d0ugal commented Apr 3, 2015

That was a pretty easy fix in the end :) Just waiting for CI to verify. Leaving this closed in favour of the PR, so check out #402 - it would be good if you could give it a test.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

2 participants
You can’t perform that action at this time.