Adding images

Storing images in this GitHub repository

Where you store images in this GitHub repository depends on where you plan to embed them. So far, I (Sam) have not run into any max image file size issues, though a GitHub does have a file size limit of 50MB. Stef recommends using https://tinypng.com/ to reduce file size, if necessary. See below for options on where to store images:

For webpages

All images are stored in the /images folder. Subfolders are there for additional organization (it makes it a bit easier to find what you're looking for). New subfolders can be added as necessary. If any current subfolder names are changed, you'll need to update the file paths wherever those images are embedded.

For blog posts

Images embedded in blog posts should be saved to the blog post's folder. The wiki details instructions for adding a new blog post and includes information on blog post organizational structure.

For events

Events operate just like blog posts! Store images in the folder with the event post you'd like to embed them in:

.
├── events/                          # all events live in here 
│   └── 2023-05-22-my-new-event      # all related files for this particular event live inside this folder
│     └── index.qmd                  # event file must be named index.qmd
│     └── image1.jpg                 # and image that is embedded in this event post
│     └── image2.png                 # another image that is embedded is this event post

What is the /img folder?

The Openscapes website was originally built using {blogdown}, which used a different file organizational structure. Rather than saving blog post images alongside the blog post file, all images were saved in ./img/blog/. Because sorting through these images and adding them to the appropriate blog post folder is very time-consuming, we decided to leave all images there and specify relative file paths from blog posts to this images in this folder. We will not be adding images to this folder moving forward.

Adding images to the website and/or blog posts

There are a number of ways to add images to webpages (e.g. Markdown syntax, ![](), the HTML <img> tag, the knitr::include_graphics() function).

During the website porting process, all images included on the main webpages (i.e. all pages except events and blog posts), were updated so that they are now being embedded using include_graphics() (the blogdown site used primarily markdown or HTML tags). A very small handful of blog posts were also updated. Please see this issue for why the switch to include_graphics() was made.

Update 2023-10-31

However, for portability reasons, we recommend using the language (e.g. R, Python) agnostic markdown syntax moving forward for any blog posts / events. See below for instructions on how to embed images:

OPTION 1 (RECOMMENDED): Embed images using markdown syntax

The general syntax looks likes this:

![](file/path/to/image)

All images should have alt text, and optionally, you can center the image on the page and/or adjust the size. To do that, use the following syntax:

::: {.center-text}
![](file/path/to/image){width="85%" fig-alt="alt text goes here"}
:::

OPTION 2: Embed images using knitr::include_graphics()

To add an image using include_graphics(), follow these steps:

1. Add a code chunk (keyboard shortcut Cmd + option + I on a Mac) wherever you'd like to insert an image
2. Call the function knitr::include_graphics("file/path/to/image")
3. Add code chunk options (using the syntax, #| option-name: value) for customizing how the image renders

An example:

#| eval: true 
#| echo: false
#| fig-align: "center"
#| out-width: "85%" 
#| fig-alt: "alt text goes here"
knitr::include_graphics("file/path/to/image")

Here's what the above code chunk options are doing:

• eval: tells R to execute code (this is true by default, so it's not necessary to include this chunk option)
• echo: tells R not to print the code chunk on the page (we only want to see the rendered image, not the code that's generating the image)
• fig-align: almost (if not) all images on the website are center aligned, but alternatively, you can specify "left" or "right"
• out-width: adjust size of image (I usually start at 100%, then adjust from there)
• fig-alt: for adding alt text

Adding captions below embedded images

Both markdown syntax, ![]() and knitr::include_graphics() allow you to define a figure caption:

Markdown:

![This is my figure caption](file/path/to/image)

knitr

#| fig-cap: "This is my figure caption"
knitr::include_graphics("file/path/to/image")

When using markdown, caption text is rendered smaller than body text, is a lighter gray color, and is centered below your image (which is all great!). When using knitr, caption text is rendered smaller, left-aligned, and a very light gray color (not so great).

We recommend using markdown syntax for adding figure captions, ![This is my figure caption]()

If you are using knitr, we recommend the following option for adding a figure caption:

We've defined two CSS class selectors (see .caption-text (which applies a dark gray font color and a smaller font size to text) and .center-text (which centers text) in styles.scss), which can be used to style caption text outside of a code chunk. See how the text is rendered differently when using the fig-cap option (top caption) vs. the .caption-text and .center-text class selectors (bottom caption) in the screenshot below:

To use the .caption-text and .center-text class selectors to style caption text, follow these steps:

1. Create a div below where you've embedded your image and call whichever classes you'd like to apply (for captions, that's .caption-text and .center-text using the following syntax:

::: {.caption-text .center-text}
:::

2. Add text that you'd like to style inside the fences (:::).

::: {.caption-text .center-text}
*My caption here will be a smaller font size, dark gray in color, and centered. The asterisks, at the start and end of this caption are markdown syntax for italicizing text. If you do not want the caption text italicized, omit the asterisks.*
:::

For an real "in-the-wild" example of using both knitr::include_graphics() + code chunk options for rendering an image and .caption-text and .center-text for adding/styling caption text, see lines 62-76 on the gallery.qmd file.

Exceptions

There are a couple of places where we do not use knitr::include_graphics() or markdown syntax to add images, detailed below:

Adding banner images

While there is a YAML option (title_block_banner) for adding a banner image (the long images that span the top of each webpage) to the top of a webpage, it only allows for narrow images, and therefore cuts off so much of the amazing art (and also some glitchy stuff happens to the image, as shown below; read more about issues applying banner images in this issue):

As a workaround, banner images are set inside the {.column-screen} div, which allows for the full image to appear (in all it's glory!) and stretch to the edges of the screen:

This generally works really well, however the image won't stretch larger than it's actual saved size -- so if you have a wide monitor and stretch your browser's viewport wider than, say, a laptop screen, we get this:

I (Sam) have not yet figured out a way to correct this (aside from saving the image at a larger size), so this is currently a persistent problem.

Open landscapes on the Gallery page

The gallery page opens with the four main landscape art images. The original blogdown site allowed users to click on one of these images to open at high resolution in a new tab. I (Sam) was unsure how to do this using include_graphics(), so I stuck with the same syntax as the original site (target="_blank" opens the link in a new tab). For example:

<a href="images/banner_imgs/original_banners/horst_openscapes_grassland_1500px.png" target="_blank">
![](images/banner_imgs/original_banners/horst_openscapes_grassland_1500px.png){fig-align="center" width="100%"}

Wrap text around an image

To wrap text around an image, for example, when adding a bio beside a headshot in a blog post, we use Quarto's "2 column" strategy. forum.posit.co post shows code below. Full docs here: quarto.org/docs/output-formats/page-layout.html#css-grid

::: {.grid}

::: {.g-col-4}
This column takes 1/3 of the page
:::

::: {.g-col-8}
This column takes 2/3 of the page
:::

:::