search

bxantus / mdoc

Markdown documentation viewer for Visual Studio Code
MIT License
4 stars 0 forks source link

Navigate to internal links without a file extension (for Github wiki support) #22

Closed Ryazbeck closed 1 year ago

Ryazbeck commented 1 year ago

I'm hoping to use mdoc at my org but not everyone uses VSCode, so they will use the Github wiki page instead.

My current predicament is that for internal linking mdoc expects links to .md files to have the .md extension in the url, but the Github-hosted wiki will navigate away from the wiki to the raw markdown if given the .md extension in the url.

I am hoping that mdoc could support internal linking without specifying the file extension, maybe through some kind of settings that default non-extension links to .md if necessary.

Ryazbeck commented 1 year ago

Looks like it's in how markdown-it>linkify-it is creating the token attr for href. I just added a simple + ".md" to the href attr and it works for me locally.

Can that be implemented here as an option/settings?

mdoc.defaultDocExtension: "md"

Ryazbeck commented 1 year ago

I forked and made the changes. Probably not the best way to handle it, but it works. I might play with it more later to come up with something better.

https://github.com/Ryazbeck/mdoc/blob/master/src/parser/mdParser.ts#L31

bxantus commented 1 year ago

I'm not familiar with the Github wiki format, or conventions. But I'm open to investigate this feature. Could you provide me with some sample syntax and a link to a repo in this format? (+ How to view it on the web)

bxantus commented 1 year ago

I probably would implement some fallback mechanism when a link is clicked. If the file isn't found in the repo, we would try with .md extension

Ryazbeck commented 1 year ago

I'm not familiar with the Github wiki format, or conventions. But I'm open to investigate this feature. Could you provide me with some sample syntax and a link to a repo in this format? (+ How to view it on the web)

I edited one of my repo's Wiki so you can see the different link types

https://github.com/Ryazbeck/ygwifi/wiki

Ryazbeck commented 1 year ago

I found another issue.

mdoc requires the full relative link (including subdirectory)

whereas Github wiki will fail if you provide it the subdirectory link; it must be provided only the filename, without a subdirectory.

So that means in order to use mdoc and the Github wiki I'd need to keep the whole directory flat, all markdown files in the root folder so that internal linking will work on both mdoc and Github.