https://marked.js.org/ has confusing links

[vsemozhetbyt]

Some links in https://marked.js.org/ refer to .md files. This may be confusing and the files are hardly readable.

Some of these links have their .html counterparts on the site, some have not.

https://marked.js.org/USING_ADVANCED.md
(https://marked.js.org/USING_ADVANCED.html exists)

https://marked.js.org/USING_PRO.md
(https://marked.js.org/USING_PRO.html exists)

https://marked.js.org/AUTHORS.md
(https://marked.js.org/AUTHORS.html exists)

https://marked.js.org/CONTRIBUTING.md
(https://marked.js.org/CONTRIBUTING.html is 404)

[UziTech]

Weird, I'm not sure where the .html files are coming from. @styfle aren't the docs hosted from /docs?

[styfle]

@UziTech Correct.

The reason why the html files exist is because GitHub Pages builds the docs with jekyll on each push to this folder (on the master branch).

It's a convenience feature that we don't really need because we are using marked to render the .md files on the fly.

Which part is confusing about the links?

[vsemozhetbyt]

Confusing is that the main rendered HTML page refers to the .md sources which are hard to read.

[vsemozhetbyt]

For example, in this sentence:

Marked offers advanced configurations and extensibility as well.

both links refer to unrendered .md files.

[styfle]

Ok thanks 👍

I see two points of confusion:

1. Opening the link in the new window shows the .md source which is unexpected
2. Opening the link in the same window doesn't update the URL so its not clear you're on a new "page"

Did that describe your problem?

[vsemozhetbyt]

Oh, I did not even know that I can navigate inside a page. I usually open links in a new tab.

Yes, and maybe:
3. Opening the link in the same window doesn't update the history so readers cannot go back with the "Back" browser button (they need to reload the page).

[vsemozhetbyt]

And if a reader mixes #hash navigation with re-render trick navigation the history navigation becomes very confusing.