spell out image link drama explicitly

[rusefillc]

https://github.com/rusefi/rusefi/wiki/HOWTO-contribute-to-documentation should be spelling out the complete drama of images in terms of w2-human and wiki3 co-existance

[nmschulte]

According to the GitHub markdown[/wiki] documentation, the image URLs currently on master (with leading /), are supposed to be working: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#links

Links starting with / will be relative to the repository root. You can use all relative link operands, such as ./ and ../.

... and later about images: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#images

Here are some examples for using relative links to display an image.

Context	Relative Link
In a .md file on the same branch	/assets/images/electrocat.png

---

I turned up this old github/markup issue noting a problem with their system about this that was later magically resolved; I wonder if something like this is at play again: github/markup#926

[nmschulte]

I created an issue for GitHub about this: github/markup#1619

[rusefillc]

@nmschulte they have two messes:

• wiki MD engine different from non-wiki MD engine, is not it?
• wiki root is URL where? :(
• I wonder if ticket you've linked is not about wiki while this issue is about GH wiki?

[chuckwagoncomputing]

• wiki MD engine different from non-wiki MD engine, is not it?

Yes. And wiki3 is different yet.

• wiki root is URL where? :(

https://github.com/rusefi/rusefi_documentation/

• I wonder if ticket you've linked is not about wiki while this issue is about GH wiki?

I believe that this is indeed the case.

[chuckwagoncomputing]

I've been doing some testing today, and here are my findings:

I haven't tested any MkDocs yet, but in general it works better than Github
Any request without trailing slash is 301 redirected to the URL with a trailing slash, so there's no distinction there.
So it looks like if we want to support Github wiki, we need to go back to a flat directory structure.

[mi-hol]

@chuckwagoncomputing not sure to understand where "trailing slash" is giving us problems, all cases bothering me had "missing leading slash" as root cause (see #123).

It appears to me that keeping Wiki3 and wiki2 up-to-date from the same source files and directory structure seem impossible.
This conclusion come from the various issues encountered while trying this approach.
Unless someone comes up with a "magic bullet" Plan A approach seems to have failed.

Therefore it seems now the right time to think about a Plan B approach from my view.
In this case I'd prefer to go back to defining requirements for documentation & update workflow first.

What are your views?

[mi-hol]

Question: has a "redirection approach" for wiki2 been considered ? For an example see https://gist.github.com/domenic/1f286d415559b56d725bee51a62c24a7

[nmschulte]

Question: has a "redirection approach" for wiki2 been considered ? For an example see https://gist.github.com/domenic/1f286d415559b56d725bee51a62c24a7

I think this is specific to GH Pages (GH hosted site) vs GH Wiki [pages].

---

@chuckwagoncomputing not sure to understand where "trailing slash" is giving us problems, all cases bothering me had "missing leading slash" as root cause (see #123).
It was mentioned over slack that trailing slash concern is not; GH Wiki issues a 301 redirect if a trailing slash is included, and so it's more/less irrelevant [to this discussion]:
dbh97: Any request without trailing slash is 301 redirected to the URL with a trailing slash, so there's no distinction there.
...
nmschulte: The problem I was focusing on was about leading slashes (repo-root relative) for URLs

Also, it seems links to non-pages, the "leading slash repo-root relative URL" magic works, but for files intended as Wiki pages, a leading slash should not be used (as GH Wiki assumes all pages are at the repo root). To wit, leading slashes for image-embedding works the same and can be located in non-root directory paths (edited to add: it seems image-embedding does not receive this magic); same as links to other types of assets, like tarballs, zip files, PDFs. Even markdown files not intended as wiki pages, though they are "discovered" as such and will receive GH wiki routing semantics and show as pages: So, we could have pages in sub-dirs (e.g. to aid organization), but we'd have to ensure unique names, and also this causes problems for MkDoc wiki due to how it expects hosting/routing to work (it doesn't hoist all pages to root for routing).

[chuckwagoncomputing]

@chuckwagoncomputing not sure to understand where "trailing slash" is giving us problems, all cases bothering me had "missing leading slash" as root cause (see #123).

Can you provide an example in which a leading slash produced a link or image that functioned as intended?

It appears to me that keeping Wiki3 and wiki2 up-to-date from the same source files and directory structure seem impossible.
This conclusion come from the various issues encountered while trying this approach.
Unless someone comes up with a "magic bullet" Plan A approach seems to have failed.

I haven't given up yet.

Question: has a "redirection approach" for wiki2 been considered ? For an example see https://gist.github.com/domenic/1f286d415559b56d725bee51a62c24a7

We don't have that level of control over the Github wiki. It's a magic black box that we can't stick our fingers in.

[chuckwagoncomputing]

I don't know how I thought flat directory structure helped, but now I can't reproduce it. Anyhow, here are my findings as of now.

Yes, the sidebar handles trailing slashes opposite of everything else (#267). We'll have to make that a full link, but that's OK because MkDoc's sidebar comes from mkdocs.yaml, not _Sidebar.md.

[mi-hol]

We don't have that level of control over the Github wiki. It's a magic black box that we can't stick our fingers in.

I couldn't describe my reasoning for concluding that Plan A is a dead-end than by using these words.
IT is like mathematics, an always working mathematical equation is required to transform source A to target B.
I'm really sorry to spell it out but what solution ideas are there to find a "working mathematical equation" that solves our issues?

[chuckwagoncomputing]

In this case, none of us have ever done math before, and the only way to find out how math works is to put numbers in the black box and see what numbers come out. And yell at clouds.
Just because we don't know what the mathematical equation is doesn't mean that it doesn't exist.
To be honest, my faith in Github is pretty low at this point, so I'm not very sure that a solution does exist, but I'm also stubborn.

[mi-hol]

Just because we don't know what the mathematical equation is doesn't mean that it doesn't exist.
To be honest, my faith in Github is pretty low at this point, so I'm not very sure that a solution does exist, but I'm also stubborn.

I like perseverance but the requirement to find a better solution for documentation editing incl ending the "broken links drama" will shortly have it's 3rd anniversary with no solution idea voiced so far. (see #210)
Is this a good situation for a project to be in?

[mi-hol]

I've started to collect documentation related requirements in #297.
Please comment there for any feature missed

[rusefillc]

I've does that solve this issue?

[rusefillc]

Now that we have #293 done what does it mean for images?

[chuckwagoncomputing]

Current status of this is that we have done all we can, and Github doesn't care.

[chuckwagoncomputing]

I have received a reply from Github. Here is the relevant part of it.

I was able to reproduce this behaviour and have escalated it to our engineering team for investigation.
Unfortunately I can't make promises around specific changes or updates, but please trust that your report is in good hands.

[chuckwagoncomputing]

Response from Github:

Our engineers have looked at this problem and determined that fixing it would be inconsistent with the standard behaviour for relative image paths. (https://www.w3schools.com/html/html_filepaths.asp)

As another solution however, you may wish to change how you link to images throughout the wiki,

Currently your images are linked as Images/triggers/trigger_TT_TOOTHED_WHEEL_36_1.png which depends on the trailing slash on the page URL not being present.

You could change to either full non-relative paths or root based paths e.g. /rusefi/rusefi/wiki/Images/triggers/trigger_TT_TOOTHED_WHEEL_36_1.png. This could be changed across the page, or the wiki with a find and replace operation.

TL;DR: WONTFIX, here's a workaround incompatible with Wiki3

edit: AND THEY REALLY LINKED W3SCHOOLS 🤡

[mi-hol]

@chuckwagoncomputing nothing we can do seems left, right?
Suggest to close

[chuckwagoncomputing]

Yep