broken markdown & nav for napari-properties-viewer about napari-hub HOT 10 CLOSED

Okay so there are three aspects that you've identified to this issue:

1. markdown nav breaks when there are invalid headers – bug; fixed by #220
2. missing image due to it being a relative link – do you desire to add support for resolving relative links as a new feature?
3. image appearing in h2 due to no newline between it and a separator – however this is how the syntax works and I believe that we shouldn't fix users' faulty markdown

How would you like to approach (2) and (3) @neuromusic?

from napari-hub.

for 2, no... let's not try to add support for this (yet). instead, let's add an entry to the FAQ "Why aren't my images rendering on my plugin description?" and clarify that we only support absolute links.

for 3, that's interesting. Github-flavored markdown must not support the alternate syntax, because it renders as a separator on the Github repo: https://github.com/kevinyamauchi/napari-properties-viewer

I think folks will be surprised if we are rendering markdown differently from Github... if this is because of a GFM difference, should we consider switching to GFM? is this easily supported by our markdown parser? e.g. with marked its just a single option to switch to the GFM spec

from napari-hub.

It looks like like (2) and (3) are both caused by the fact we don't support relative images. It should be easy to support provided we follow a few heuristics:

1. If the image is an absolute URL, then use the URL directly
   • Example: https://example.com/image.png
2. If the image is a relative URL but does not start with a prefix, then append to repo's raw URL.
   • Example: resources/image.png -> https://raw.githubusercontent.com/<owner>/<repo>/main/resources/image.png
3. If the image is a relative URL but starts with a ./ prefix, then append to repo's raw URL with ./ removed:
   • Example: ./resources/image.png -> https://raw.githubusercontent.com/<owner>/<repo>/main/resources/image.png
4. If the image is a relative URL but starts with a ../ prefix, then the description is likely stored in .napari/DESCRIPTION.md. This means we can remove the ../ prefix and add it to the repo's raw URL:
   • Example: ../resources/image.png -> https://raw.githubusercontent.com/<owner>/<repo>/main/resources/image.png

For reference, here are examples of plugins that fall under the above use cases:

1. Absolute URL: https://www.napari-hub.org/plugins/napari-segment-blobs-and-things-with-membranes
2. Image without prefix: https://www.napari-hub.org/plugins/napari-animation
3. Image with ./ prefix: https://www.napari-hub.org/plugins/napari-DeepSpot
4. Image with ../ prefix: https://www.napari-hub.org/plugins/napari-annotator

There are a couple of edge cases we would need to think about though:

1. What if the default branch isn't main? We can try master, but even then, users can specify a different branch as the default.
2. What about versions? We currently don't support showing different versions for plugin on the napari hub, but if we decide to add it in the future, the URLs may change between versions, and there may not be a corresponding version branch / tag for the repo.

Despite these edge cases, I still think it would be a good idea to add the above image resolution logic because in the best case scenario, we'll still be able to show relative images for plugins. However, I wonder if we should instead nudge plugin developers to use absolute image URLs. Maybe it's something we can include in the preview page?

thoughts? @neuromusic @kne42

from napari-hub.

those heuristics sound reasonable

re: the edge cases, when we trigger a fetch to Github, we use the latest URL, but there should also be a permalink for that commit... if we can get that link somehow that would resolve edge cases 1 and 2. I know how to do this through the Github UI, but not the API

from napari-hub.

I wonder if we should instead nudge plugin developers to use absolute image URLs. Maybe it's something we can include in the preview page?

If I recall, we kinda do this... at least in the sense that relative URLs should break in the preview page... but we don't offer any nudge or specific warning

from napari-hub.

there should also be a permalink for that commit... if we can get that link somehow that would resolve edge cases 1 and 2. I know how to do this through the Github UI, but not the API

oooh I like this idea, it looks like we can get permalinks by using the commit directly instead of main, so something like this:
https://raw.githubusercontent.com/ebouilhol/napari-DeepSpot/ee94c05f78b7294ff193555475b1c050694711fd/image/napari.png

@potating-potato @klai95 any thoughts? we could include the plugin repo's git hash in the plugin data and use that to resolve the images (assuming they're using github)

another option is to overwrite the plugin description markdown at the indexing stage so that every relative image resolves to a permalink

from napari-hub.

another option is we stick with the current behavior and document that relative images are not supported (not sure if we do this already). definitely the easiest to do, but not sure what plugin developers prefer

from napari-hub.

if you're confident that (3) is due to the relative images issue and not a markdown rendering issue, then I'm happy calling this an "enhancement" rather than a "bug" and in the meantime make sure that we document that we only support absolute links.

from napari-hub.

@neuromusic yeah (3) is definitely because it's a relative image haha. I have a POC implemented on the frontend for resolving relative images, and it fixes (3)

I'm happy calling this an "enhancement" rather than a "bug" and in the meantime make sure that we document that we only support absolute links.

that makes sense, marking this as an enhancement

from napari-hub.

closing this issue in favor of #541 since the only remaining task for this issue is adding support for relative images

from napari-hub.