Linking between pages breaks github navigation
crazycodr opened this issue · comments
When linking between documents, the links are not automatically adapted to fit viewdocs link structure.
If i follow the structure of the links in your examples to create relative links between my pages, then the github markdown viewer's linking is broken.
For example, linking to my "object-collection.md" page using the github navigation works perfectly, but doesn't on viewdocs because it doesn't adapt the link automatically to "http://crazycodr.viewdocs.io/data-collection/object-collection.md" and instead assumes that my link is "http://crazycodr.viewdocs.io/object-collection" which is totally wrong.
To fix this with viewdocs, i'd have to hardcode all my relative links with "data-collection/object-collection.md" but after doing that, obviously, people can't navigate using the integrated github markdown viewer...
What is you take on this? Anything planned or actually exists to fix this?
Yeah, it's a little annoying in that regard, but I don't really ever
intended people to click through links when viewing on Github. Why are they
viewing on Github when you have such a good documentation site now? If they
were looking at the files while checked out on their computer, the links
would be useless anyway. I think of Github viewing as looking at the
source, nothing more.
On Thu, Nov 14, 2013 at 7:32 AM, Mathieu Dumoulin
notifications@github.comwrote:
When linking between documents, the links are not automatically adapted to
fit viewdocs link structure.If i follow the structure of the links in your examples to create relative
links between my pages, then the github markdown viewer's linking is broken.For example, linking to my "object-collection.md" page using the github
navigation works perfectly, but doesn't on viewdocs because it doesn't
adapt the link automatically to "
http://crazycodr.viewdocs.io/data-collection/object-collection.md" and
instead assumes that my link is "
http://crazycodr.viewdocs.io/object-collection" which is totally wrong.To fix this with viewdocs, i'd have to hardcode all my relative links with
"data-collection/object-collection.md" but after doing that, obviously,
people can't navigate using the integrated github markdown viewer...What is you take on this? Anything planned or actually exists to fix this?
—
Reply to this email directly or view it on GitHubhttps://github.com//issues/5
.
Jeff Lindsay
http://progrium.com
If you end up on the git hub page from, let's say another web site, a tweet, packagist.org if you are using PHP and don't see that there is a link in the initial readme that tells you to use "viewdocs.io", you'll try to browse the source using GitHub and it'll look like it's broken...
Three things may happen from there:
- Users leave the github project page because they think the project is not serious due to documentation issues
- Users leave a useless issue in the issue tracker for the project, doesn't help the package maintainer at all, he has other things to do...
- Package maintainer is tired of always responding to these tickets, decides not to use viewdocs.io and you lose credibility
All in all, viewdocs is a great tool to add an additionnal layer of presentation, but it musn't break other existing ways. Another point is that if someone has a markdown viewer on their machine to inspect the local docs cloned from github, he won't be able to navigate it with the viewdocs url requirement. Yes, he won't have access to the templating system or the hacking possibilities, but thats just it, they are added features!
I'm not sure a strongly agree with some of your points. I should point out
that if you had a good solution as well, I'd be more easily convinced.
On Thu, Nov 14, 2013 at 8:07 AM, Mathieu Dumoulin
notifications@github.comwrote:
If you end up on the git hub page from, let's say another web site, a
tweet, packagist.org if you are using PHP and don't see that there is a
link in the initial readme that tells you to use "viewdocs.io", you'll
try to browse the source using GitHub and it'll look like it's broken...Three things may happen from there:
- Users leave the github project page because they think the project
is not serious due to documentation issues- Users leave a useless issue in the issue tracker for the project,
doesn't help the package maintainer at all, he has other things to do...- Package maintainer is tired of always responding to these tickets,
decides not to use viewdocs.io and you lose credibilityAll in all, viewdocs is a great tool to add an additionnal layer of
presentation, but it musn't break other existing ways. Another point is
that if someone has a markdown viewer on their machine to inspect the local
docs cloned from github, he won't be able to navigate it with the viewdocs
url requirement. Yes, he won't have access to the templating system or the
hacking possibilities, but thats just it, they are added features!—
Reply to this email directly or view it on GitHubhttps://github.com//issues/5#issuecomment-28496374
.
Jeff Lindsay
http://progrium.com
I'm not a GO programmer although i haven't tried yet, but it shouldn't be that hard to supplement relative links in the fetched data with the base url composed of "user.viewdocs.io/project/".
Which points do you not agree with?
That it's that big of a problem. Unless all those things have happened to a
project of yours already.
If anybody else has thoughts, weigh in. I'd accept a PR that fixes relative
URLs.
On Thu, Nov 14, 2013 at 8:13 AM, Mathieu Dumoulin
notifications@github.comwrote:
I'm not a GO programmer although i haven't tried yet, but it shouldn't be
that hard to supplement relative links in the fetched data with the base
url composed of "user.viewdocs.io/project/".Which points do you not agree with?
—
Reply to this email directly or view it on GitHubhttps://github.com//issues/5#issuecomment-28496894
.
Jeff Lindsay
http://progrium.com
In my case. I wanted this because it's a pain to write /reponame in all relative links. And I also tend to browse md files in github repos.
Great marksteve, i really couldn't have come up with that... although i must say this go language is intriguing, i'll have to take a look at it eventually!
@crazycodr I'm pretty sure this is available on current master and already deployed... #justsaying ;)
Again, nice work @fgrehm ... shall we close guys?
Excellent, i'll test it soon, i trust you did good :) 👍