Display an image in a narrative

Apologies if this has already been asked, but how does one link an image file to a narrative view. For example, the SA group show a graph here. I have uploaded a zambiawaves.png to the s3 bucket and then referenced it in the narrative as:

Wave Dynamics

However there is no ‘Wave Dynamics’ page (tried with and without the .png ending). Again I know this is basic, but what am I missing?

Thanks in advance

This may seem basic, but you’re bumping into something much more complex than it seems on the surface! No worries for asking.

Unfortunately we haven’t yet implemented a general-purpose way to include images in narratives for Groups. The lack of this is something we’re aware of and have recently been discussing amongst the Nextstrain team, but we don’t have any concrete timeline to address it at the moment. In the meantime, there are a few workarounds. Hopefully one of them will be suitable for your needs!

  1. You can host the images elsewhere and hotlink to them from the narrative. This is what the NGS-SA group’s example that you linked to does (https://www.krisp.org.za/imagesBIO/mapnarrative.png).

  2. You can embed the images directly into the narrative markdown using base64-encoded data: URLs. We don’t have documentation for this, but one way you can construct such a URL is running:

    printf '![description](data:image/png;base64,%s)' \
      "$(base64 --wrap=0 < zambiawaves.png)" \
      > image.md

    and then copying and pasting the contents of image.md into your narrative Markdown. It will be a single very long line of text. Note that you may need to adjust the MIME type, for example if you have a JPEG (image/jpeg) instead of a PNG (image/png).

  3. You can host the images in your group’s bucket, but only if the group is public. You need to use a direct AWS S3 URL:


    The biggest downside here is that these will eventually stop working as we plan to transition away from direct S3 access for Groups.

1 Like

Thanks @trs for your response. Have tried all three and so far no luck!

I thought option three would be the easiest to get to work, but even though I can access the image with the address:

when I insert it into the md as:
# [Zambias three waves](https://nextstrain-sc2zampub.s3.amazonaws.com/zambiawaves.png)
The charts on the right hand side show...

I get an error:
"Error loading the datasets for this narrative slide"

I see you use a ! prefix for the image rather than a # heading - have played around with that, but not got it working. Am I missing something obvious?

Any suggestions on a good hosting site if you don’t have your own to host an image or two?

Ah, sorry I didn’t give a complete example. What you’re running into is a little funkiness in how narratives work, and it’s a little confusing at first.

The narrative headings (# …) always have to be links to a Nextstrain dataset. In a typical slide, that dataset is shown in the right hand panel and the associated Markdown prose under the heading is shown in the left hand panel.

However, there’s a special-cased “fenced” block (```) syntax you can use to also provide Markdown prose for the right hand panel instead of showing the dataset. This is what you’ll want to use to display the image there.

Here’s a complete example:

# [Zambia's three waves](https://nextstrain.org/groups/SC2ZamPub/ncov/africa/zambia)

The charts on the right hand side show the Tests, Test Positivity, Cases and Deaths for the 80 days before and after the peak of each of the three waves as follows:
1. Wave 1: 2020-05-13 to 2020-10-20
2. Wave 2: 2020-11-06 to 2021-04-15
3. Wave 3: 2021-04-13 to 2021-09-20

A few key observations can be made:
+ Wave 1 had signifiucantly lower testing than the other waves
+ Test positivity was the most consistent metric between all three waves, with wave 2 having the lowest positivity
+ Cases and deaths were significantly higher in wave 3 

![plot with four panels, showing …](https://nextstrain-sc2zampub.s3.amazonaws.com/zambiawaves.png)

Thanks for your patience @trs - with your help it is now working perfectly!

1 Like

I think it is safe to say that I would never have stumbled upon that solution on my own!

Totally. Things like this are why we need better docs around narratives (and many other things). We’re all working on it, but it’s a slow process! :slight_smile: Thanks for bringing up your questions and stumbling blocks here. It really helps identify important gaps in the docs and also provides a temporary bridge over that gap that others can learn from in the meantime.

Thanks @trs

One other minor thing on inserting an image. Is there a way to autoscale its size based on screen size? I have shrunk it down so it fits on a small laptop screen, but wondering if there is a more sophisticated approach?

Ah, that looks like an oversight in the built-in styling for narratives. Unfortunately I don’t think there’s a more sophisticated workaround you can use other than what you’ve done, but I’ve filed a small change to fix it. Thanks for the report!