Images in output.md not rendered when converted to html

[drpatelh]

The template contains a process called output_documentation that converts the pipeline's output documentation i.e. docs/output.md to html format in order to be stored with the results. However, if there are images embedded or linked in this document then these wont be rendered properly and so the links just appear to be broken. Im wondering whether using absolute instead of relative paths will solve this... 🤔

[ewels]

Good spot! Absolute paths is one way, or we could also copy the images directory to the results folder. The best way would be to base64 encode the images so that they are included in the HTML file.

[ewels]

To be honest, it wouldn't be a terrible idea to rewrite this functionality. I don't love that it's done with an R script, as it means that every pipeline has to have R in the container. Could be better to have it in a Python script, as we're using conda..

[drpatelh]

Issues with needing R aside (which I agree isn't ideal for a single package), I'm going to go one step further and ask if we actually need to generate this file at all? It's a duplicate of what's already available online so why not just use/point to that one exclusively for results documentation?

[ewels]

Yes, the same question passed through my mind to be honest. It is a relic of the early days of the NGI pipelines really. But I think that is probably is still useful in our use case - specifically when pipeline results are delivered to a user who has no knowledge (or interest) of the pipeline that generated those results.

I guess we could just link to the online docs though. Maybe a shortcut file?? Remember those? 😆

output_file_documentation.url:

[InternetShortcut]
URL=https://nf-co.re/atacseq/docs/output

[apeltzer]

Good point @drpatelh! If we could simply link to whats online I think that's the best way to do it and also is anyways the same piece of information.

[drpatelh]

I guess the only real problem is that output.md will change over time and so we will need a more dynamic way of referring to the docs for that particular pipeline release. At the moment, thats not a problem because it will be generated from the docs at the time.

[maxulysse]

We can always refer to a permalink of the docs

[ewels]

I just tested the example output_file_documentation.url file above and it actually worked pretty nicely on my mac..

Referring to specific versions won't work on the nf-core website, but pinning to a commit hash on GitHub.com should be fine..

[ewels]

Looks like you can use tag (release) names directly in the GitHub URLs too, so we don't have to worry about fetching commit hashes: https://github.com/nf-core/atacseq/blob/1.0.0/docs/output.md

[ewels]

I have now rewritten the markdown conversion in Python and this includes base64 including images.

See #501