2024_08: determine image link+alt text syntax to use in .md files

[ljmoody]

~July 25: broken image links identified in Team PSD Manual Chap 12 (instructions to authors)

@lijenn's July 24 post on research repo card 550:

We need to use the raw image file link for all Bookdown/Manual markdown files (Team PSD and MTL Manual).

@ljmoody Can you confirm if this is where we'd use Find and Replace in GitHub Actions Workflow? Or is it only for the Sim UI SD models?

If we could find all instances of https://github.com/lzim/teampsd/blob/ and replace it with https://raw.githubusercontent.com/lzim/teampsd/ it would fix all existing broken images in both manuals.

[ljmoody]

@lijenn, I can't confirm re: Find & Replace question above because I haven't used that F&R function before. I'm only familiar with the F&R capability within each markdown file.

Re: the syntax, I'm confused about which is correct because of the following. Should we meet and discuss? Whatever we change should be a blanket instruction for all .png files; I'd like to be sure we're on the same page so whatever we do moving forward is consistent--and works!

These two images are not rendering in the Team PSD Manual:

This image is rendering in the Team PSD Manual:

Here's the syntax from Chap 13 for the two images you updated last week:

Instructions I've been following for images:

All of this together makes me think it might not be the "blob" or "raw.githubusercontent" part of the code that makes images render correctly. Is it possible that both the raw.githubusercontent tag and/or the png image tag with raw=true at the end both accomplish the same thing?

[lijenn]

@ljmoody Nice catch! Thanks for the reminder. It's tough when not all the images use the same style and formatting. Not sure if we have the bandwidth for this or if we could somehow use FNR to standardize the markdown code for all images (@matthewtomo could provide support on this?), but I agree with you that we need blanket instructions for fixing them.

It might be easier to add the raw=true, but we need to test it out on other broken images/the code. Do you want to test it out to see if that fixes the broken images in Ch 13 in the Team PSD Manual (Ch 12 in the GH-pages branch)?

Lmk if I understood your concern and if we need to hop on a call.

[ljmoody]

8/1/24 @lijenn & @ljmoody met to discuss making image syntax consistent throughout both manuals.

• The "(#DontLink) tag is not necessary necessary to keep at the end of image tags; they are not auto-linked to the origin file, so users cannot click and follow the images as links.

• Broken links in Chap 12 of the Team PSD Manual were updated successfully using both image syntax strands below. We recommend choosing one and using it as a standard.

Option 1: <img src = "https://github.com/lzim/teampsd/blob/ghpages/images/ch7_s1_manuscript_workflow.PNG?raw=true">

Option 2: ![Make a manuscript contribution workflow] (https://raw.githubusercontent.com/lzim/teampsd/gh-pages/images/ch7_s1_manuscript_workflow.PNG)

• We also recommend, when time/resources are available, to review/update/correct all links in the manuals. It may be possible to do this via Find and Replace.

[lijenn]

Discussed sim_ui_workflow 8/7:

• @jamesmrollins @ljmoody @matthewtomo @lijenn
• Are the Team PSD and MTL manuals considered a product of the government? Yes
• If so, do we need 508 compliance with these manuals? Yes
• Specifically images: do we need to have alt text? Yes

[ljmoody]

• [x] also need to consider alt text and include that in templated syntax

[matthewtomo]

This issue was addressed in #3246

Discussed 8/20/24 @matthewtomo @jamesmrollins @lijenn ...

• For images make sure to use following format to include alt text properly: <img alt="Alt Text" src="Path/URL to Image">
  • Make sure to include "?raw=true" at the end of the url to just get the image and not the link to the image in GitHub
  • Example: <img alt="An image of our registration page" src="https://github.com/lzim/mtl/blob/gh-pages/images/self_registration_popup_team_name.png?raw=true">

• We have settled on a sytnax, so I will close this issue. fyi: @jamesmrollins @lijenn @ljmoody

[matthewtomo]

• The decided upon syntax ("?raw=true") was the cause of images sometimes not rendering.
• The comment from #3246 has been updated to address this, with a new syntax.
• I want to ping everyone here as well to make sure everyone gets the message on the new GitHub Pages image syntax standard.

Discussed 8/20/24 @matthewtomo @jamesmrollins @lijenn

• Bookdown currently does not properly render all images (issue appears intermittently).

  • Appears that this can be resolved by deleting and re-adding the source of an image to trick bookdown into re-rendering it

• For images make sure to use following format to include alt text properly: <img alt="Alt Text" src="Path/URL to Image"> where "Path/URL to Image" takes the format "https://raw.githubusercontent.com/OWNER/REPO/gh-pages/PATH_TO_IMAGE_IN_REPO" or looks like "https://raw.githubusercontent.com/lzim/mtl/gh-pages/images/self_registration_login_screen.png"

  • ~Make sure to include "?raw=true" at the end of the url to just get the image and not the link to the image in GitHub~ Update: the "?raw=true" format was the cause of images sometimes failing to render. DO NOT USE THAT FORMAT.
  • Example: ~<img alt="An image of our registration page" src="https://github.com/lzim/mtl/blob/gh-pages/images/self_registration_popup_team_name.png?raw=true">~ <img alt="An image of our registration page" src="https://raw.githubusercontent.com/lzim/mtl/gh-pages/images/self_registration_popup_team_name.png">

fyi: @ljmoody

fyi: @jamesmrollins @ljmoody @lijenn @matthewtomo

#ADJUDICATE_MEMO

• The story points for this card were increased because the issue was closed prematurely.
• Since the chosen syntax standard caused a different set of issues, we had to explore:
  • The cause of the issues
  • Potentials workarounds or other syntax standards