Github Marked inline links does not work when document is uploaded to Github
Hi Guys,
I'm using Marked in conjunction with TextMate to create the documentation of my projects hosted in Github. First of all let me congratulate you guys for the great work!! The Github preview is awesome and have made my life much easier!!!
There is a small glitch however that I'd like to report, not sure if it can be fixed thou. It seems to me that Marked and Github uses a different Base reference when rendering inline links. For example:
suppose a project with this directory structure
`
project_name/
project_name/docs/
project_name/docs/readme.md
project_name/docs/somepage.md
When linking readme.md and somepage.md with markdown text
like this For more information see this [link]
(somepage.md)it will work in Marked Github css but broke when
rendered by Github itself. Github assumes that all inline links are
referenced based on the root path (in this case project_name) and
therefore for this example to work it should be written as
For more information see this [link] (docs/somepage.md)` in which
case it will work on github but not in Marked.
Would it be possible to have the path reference adjusted when using Github css in Marked?
Once again, thanks in advance.
Cheers,
Eric
Keyboard shortcuts
Generic
| ? | Show this help |
|---|---|
| ESC | Blurs the current field |
Comment Form
| r | Focus the comment reply box |
|---|---|
| ^ + ↩ | Submit the comment |
You can use Command ⌘ instead of Control ^ on Mac
1 Posted by Eric Chaves on 17 May, 2012 12:22 PM
Ops, I accidentally messed-up with final formatting. Sorry. Below is the message properly formatted.
I'm using Marked in conjunction with TextMate to create the documentation of my projects hosted in Github. First of all let me congratulate you guys for the great work!! The Github preview is awesome and have made my life much easier!!!
There is a small glitch however that I'd like to report, not sure if it can be fixed thou. It seems to me that Marked and Github uses a different Base reference when rendering inline links. For example:
suppose a project with this directory structure
When linking readme.md and somepage.md with markdown text like this
For more information see this [link] (somepage.md)it will work in Marked Github css but broke when rendered by Github itself. Github assumes that all inline links are referenced based on the root path (in this case project_name) and therefore for this example to work it should be written asFor more information see this [link] (docs/somepage.md)in which case it will work on github but not in Marked.Would it be possible to have the path reference adjusted when using Github css in Marked?
Once again, thanks in advance.
Cheers,
Eric
Support Staff 2 Posted by Brett on 17 May, 2012 12:43 PM
I just tested this out in both Marked and on Github and I'm not seeing the issue. Files within a subfolder properly reference each other through relative paths… are you sure you can replicate this?
3 Posted by Eric Chaves on 17 May, 2012 02:44 PM
Hi Brett,
I've just pushed a sample project to https://github.com/ericchaves/marked-inline and did some tests. I also tried to tabulate some results that I found.
Starting from the README.md you'll see the linking problem and how they behave differently. Links 1 and 2 work on Marked and dont work on Github.
Links 3 and 4 will work the other around, but once you start from those links It seems to me that it all resumes down to the path used to navigate between the pages, and to be honest I'm very confused right now.
Sometimes github makes the path relative to "tree/master" and sometimes it is "blob/master", and this seems to change how the links behave.
Could you help me out with this?
Also, during my tests some times Marked messed up a bit when rendering the files, adding some words or chars in same places. I took two screenshots where you can see the source and rendered output. In one of them Marked rendered a :center:"> text in one of the empty cells, and in other the text for link 4 was scrambled.
Cheers,
Eric
Support Staff 4 Posted by Brett on 17 May, 2012 03:59 PM
I think I may have already fixed the linking issue in the next version, which is what I was testing with. I'm adding a `<base>` element now that should provide better relative linking in subdirectories. That may be a while in coming out, but I'm working to push it through in the next 3 weeks.
As far as the rendering mishaps, next time you see that could you right click on the bad text and choose inspect element? You should be able to see in the markup if something was inserted there that shouldn't have been. Let me know what you find. Also, does it tend to go away on the next refresh, or does it continue to be a problem after a file update?
5 Posted by Eric Chaves on 18 May, 2012 01:48 PM
Hi Brett,
I'm having a hard time to make the render the bug again. But when it happened by coincidence I inspected one of them as mentioned (with inspected element) and indeed text was present in the html output, so I guess it was inserted. The one I inspected was the table rendered with the scrambled text ( :center:"> ) without the parentheses.
At the time it did not go away with refresh, but it goes away when updating anything in the document, for example, adding a char in a cell or changing some text.
But reproducing the exact code right now does not produce the bur, neither undoing the text changes until it get back to the point where it happened. So I really cannot say what was going on. But I keep an eye on it.
Cheers,
Eric
Support Staff 6 Posted by Brett on 18 May, 2012 01:55 PM
It's possible that the scroll-to-edit feature interfered. I've done my best to make it smart enough not to interrupt a tag, but it inserts a b#firstdiff element into the dom so it knows where to scroll to, and on occasion it causes rendering errors. Not sure that's what you saw, but it sounds feasible. I'll continue to make that smarter.