Update docs for relative intra-site links support

[damithc]

Current:

• This works: <img src="images/createNewProject.png">
• This does not: ![](images/createNewProject.png)
  (but this works ![]({{ baseUrl }}/images/createNewProject.png))

Suggestion: support relative URLs for the latter as well.

Note: this is a left-over from #677

UPDATE: as mentioned in the thread below, the issue has been resolved. Just need to update docs a bit.

[alyip98]

I can't reproduce this issue in v2.5.1

[damithc]

@sijie123 do you remember the details of this issue?

[damithc]

I can't reproduce this issue in v2.5.1

This issue probably flares up only when an include chain is involved, or when a sub-site is involved.

[damithc]

I can't seem to reproduce the said problem; was it fixed 'accidentally'? 🤔 I remember we decided at the time this was a hard problem to solve though.
Even if it is fixed, it is still worth finding out how it got fixed as we can break it again the same way. Perhaps look through the history of the relevant files?

[sijie123]

This problem should have been fixed in #826. Somehow we forgot to resolve the issue when the PR was merged.

The final solution was to go the hard route and change our parser. If I recall correctly, I wrapped a hidden div around every instance of include.
#826 allows us to become contextually aware of the include locations. Previously, we simply "copied and pasted" the target code as if we were doing a find and replace.

If a referenced b as ./sub_folder/b, and b referenced c as ./sub_folder/c, then originally, a will be unaware that b has to include c by traversing further down the filesystem. a will reference c as ./sub_folder/c, since we simply "copy-and-paste" whatever was in b. This creates an invalid reference.

The new behaviour is that we wrap an invisible div that keeps track of where the target code is. Now, a is aware that it included "sub_folder/b", which itself includes "sub_folder/c".

As a result, the [](..) syntax can work properly because the references are now intact.

[damithc]

This problem should have been fixed in #826. Somehow we forgot to resolve the issue when the PR was merged.

The final solution was to go the hard route and change our parser. If I recall correctly, I wrapped a hidden div around every instance of include.
#826 allows us to become contextually aware of the include locations. Previously, we simply "copied and pasted" the target code as if we were doing a find and replace.

If a referenced b as ./sub_folder/b, and b referenced c as ./sub_folder/c, then originally, a will be unaware that b has to include c by traversing further down the filesystem. a will reference c as ./sub_folder/c, since we simply "copy-and-paste" whatever was in b. This creates an invalid reference.

The new behaviour is that we wrap an invisible div that keeps track of where the target code is. Now, a is aware that it included "sub_folder/b", which itself includes "sub_folder/c".

As a result, the [](..) syntax can work properly because the references are now intact.

Fantastic! 🎉 thanks for the fix and the explanation @sijie123
Somehow, I didn't realize the problem has been fixed.

@alyip98 @openorclose Sorry about the false alarm. See if any of the explanation above can be incorporated into code comments to aid future devs. We can also update user docs. Due to way the examples are given in the current docs, it may appear (at first glance) that markbind syntax needs to be absolute and html links can be relative.