R Markdown | Thought splinters

Using GitHub as a Mentoring Tool

Sun, 01 Aug 2021 00:00:00 +0000

Beginner, Intermediate, and Expert Level

For several years I am interested to learn R, the free software environment for statistical computing and graphics. After

reading several books,
finished some (paid) introductory (MOOC) courses successfully with Coursera
and especially some smaller (paid) projects

I would say that I am now (stuck?) on an intermediate skill level. I believe that this is the most challenging step in progressing to an expert for a self-determined learner. There are always so many different avenues to follow up. This is especially true with R and its

ever increasing amount of new R packages (To date: 20010 (MRAN) resp. 17954 (CRAN), 3452 (Bioconductor).
hundreds of books (see: the searchable list on r-project.org, a curated list on GitHub by Roman Tselgelskyi, but also my Wakelet on free R Books
an unknown number of (free) online tutorials (see the general list and university listed free R tutorials by Pairach Piboonrungroj and my Wakelet on learn R programming)

Comparing my skill level with the three learner paths suggested by RStudio Education, I could affirm my personal assessment. From the six tasks proposals on the intermediate path

grab some R cheat sheets
learn to get help (see, for instance, my activities on StackOverflow)
improve your visualizations
develop interactive applications with htmlwidgets and Shiny
simplify your model explorations with tidymodels
explore other specialized packages

I have some skills with the first three, and I also experimented already with Shiny. I even had worked on some steps at the expert levels by writing an R package: (bib2academic got 16 stars, but I did not manage to submit it to CRAN. It is now obsolete as a similar function was integrated into the Academic Hugo website (now Wowchemy website builder).

Project for Motivation Necessary

But to continue this path, I would need some strong motivation. I tried, for instance, to read the (not yet finished) book Mastering Shiny. As with all books and papers by Hadley Wickham, it is well written and exciting. But to learn continuously, I would need a practical project where I get not only real-world challenges but also a strong personal motivation to complete the product. In finishing the project/product, I would have to learn to overcome several real-world challenges where I would need to look for help and consult/experiment with several new functions or packages.

But this strategy has two advantages:

It is very laborious as the specific questions are not (yet) clear enough. Fora like StackOverflow are not suitable as the problem space is not delimited, a concrete coding question with a REPREX (REPRoducible EXamples) is not available.
It is error-prone and not efficient. Am I posing the right question? Do I look at the right places? It is not guaranteed that one finds the optimal solution. This is particularly awkward if the answer in the R community is very well known.

Looking for a Human Mentor

I believe with a mentor, one could overcome these insecurities fast. The mentor — an experienced user — could ask questions to narrow the search space and point out helpful hints about what and where to look. Wikipedia, for instance, has established a similar program for their user community called Adopt-a-user.

The Adopt-a-user program is designed to help new and inexperienced users by pairing them with more experienced Wikipedians. These editors (referred to as adopters or mentors) will “adopt” newer users, guiding them along the way as they learn about Wikipedia and its various aspects. (Wikipedia)

In Wikipedia, the intention is to help novice contributors get orientation and some guided practice with the very complex rule set for writing or changing Wikipedia entries. My thought is to find a mentor to advance at the intermediate level. I think there is plenty of material for the R beginners freely available. But more important: You will learn R from scratch as an individual and do not need to worry at the beginning stage about an already developed complex rule which you have to observe and follow.

As far as I know, there is no mentor program for R users. The next best alternative is a more open and friendly community. An excellent example, in my opinion, would be the RStudio Community. But even there, you should have a concrete question to ask.

GitHub as a Mentoring Tool

An instructive example

I recently found out that GitHub could be used as an educational tool. I will you give an example which was very exciting for me:

Often I was confronted with the problem of how to calculate and format nicely a contingency table in R. The free web material on the web on this question is abound (e.g., Datacamp, Data Science Central, R-Bloggers, TechVidvan, Statology, …). But many examples still teach the Base R commands. They do not mention new procedures with the tidydata approach and related packages like tidyr. And they do not worry about outputting the table in a publishing-ready format.

There are many contingency tables published in the recently finished books Introduction to Modern Statistics.

Table 1: Descriptive statistics for the stent study.
	30 days	365 days
Group	Stroke	No event	Stroke	No event
Control	13	214	28	199
Treatment	33	191	45	179
Total	46	405	73	378

I could look up the source code from lines 85-101 via GitHub and learn how to produce the above table. (In the following code chunk, I have focussed on the table appearance and left out different previous data transformations to prepare the two data sets stent30 and stent365. Furthermore, the code differs somewhat from the original due to some CSS styles of this website.).

```{r stent-study}
suppressMessages(library(janitor))
suppressMessages(library(kableExtra))
suppressMessages(library(openintro))
suppressMessages(library(tidyverse))

stent %>%
  mutate(group = str_to_title(group)) %>%
  pivot_longer(cols = c(`30 days`, `365 days`), 
               names_to = "stage", 
               values_to = "outcome") %>%
  count(group, stage, outcome) %>%
  pivot_wider(names_from = c(stage, outcome), values_from = n) %>%
  adorn_totals(where = "row") %>%
  kbl(linesep = "", booktabs = TRUE, caption = "Descriptive statistics for the stent study.",
      col.names = c("Group", "Stroke", "No event", "Stroke", "No event"),
      table.attr = "style='width: 75%;'") %>%
  add_header_above(c(" " = 1, "30 days" = 2, "365 days" = 2), extra_css = "border-bottom: 2px solid") %>%
  row_spec(1, extra_css = "border-top: 2px solid") %>%
  row_spec(3, extra_css = "border-top: 2px solid") %>%
  kable_styling(bootstrap_options = c("striped", "condensed"), 
                latex_options = c("striped", "hold_position"),
                full_width = T, position = 'center')
```

Lesson learned

Looking into the source code at GitHub, I learned several issues:

I experimented already with the janitor package, and I am happy to get the confirmation that it is a widely used package to “provide quick counts of variable combinations (i.e., frequency tables and crosstabs)” and to “format [nicely] the tabulation results.” (From the Janitor package description.)
I also did know about the kableExtra package and had the kable_styling function already used several times.
The other kableExtra functions (add_header_above(), row_spec(), kbl()) I had not used before. Especially add_header_above() has an important role for special headings in contingency tables.
The parameter extra_css was entirely new for me. I have never heard about it and didn’t even know that it exists.

For me, this learning experience was very instructive! I admit that this example could have been asked via a friendly forum: For instance: “How could I produce a contingency table formatted professionally for print by using the tidyverse approach?” Additionally, one would have to provide some code to show where one stands and what approach one is using.

Looking Experts over their Shoulders

But this was just one example where I knew about the problem and had already tried several approaches to find a solution. But what about code patterns I didn’t even know and could therefore not ask the right question?

Finding a GitHub project with code snippets one needs urgently is just the beginning. There is a big chance that the same repository (aka ‘repo’) hides more code snippets to learn from. And maybe the person behind this one GitHub repos maintains other repositories that are also very interesting?

In my case, it turned out that Mine Çetakaya-Rundel, one of the authors and the person responsible for the repository management, has educational approaches that are similar to mine. But she is way off more skilled in R and statistics. I am especially interested in her usage of the learnr package for interactive tutorials and have watched a series of three videos on Teaching Statistics and Data Science Online.

In a certain sense, she functions as a mentor for me — even if she doesn’t know about it 🥸. Meanwhile, we had some exchanges on GitHub issues as I am interested in learning how to use the learnr package for introductions into statistics via R-Tutorials. Regularly if I find a problem as a user reading and following the tutorial exercises, I try to fix the code in my fork and send the solutions as pull requests (PR) to Mine. Besides learning to use GitHub in a collaborative setting, I have already profited in many ways. I learned about packages I have never heard of (see, for example, the list of packages used for the book) and saw code snippets that transformed data in a much more elegant way as I used to do.

Summary

To inspect code on GitHub is a suitable strategy for intermediate (programming) learners. I illustrated it with an R example, but I think you could generalize it as a learning strategy. I recommend the following steps:

Note names and/or repositories you learned from successful internet recherche. By searching answers or asking questions via StackOverflow, you will encounter the same names, blog addresses, Twitter messages, repos again and again.
Look around if these person/websites generally work on problems you are interested in. Look into the profile and follow the activities of these persons on their blog, Twitter, YouTube, GitHub … accounts.
Decide on a person and select a specific project. I recommend focusing not only on a particular person but also on picking one project to concentrate on. Ideally, it is a current project the person is still interested in and produces code you want to learn and use for your own work later on.
Think about a possibility to get involved in the project. The idea is to give the person and the community something back for its/their mentoring function and commit yourself to relevant real-world problems. The possibilities depend on your skills and interests. It may be advertising the project, writing a favorable review, fixing typos, commenting via the issue part of the repo, recommending code changes via PRs, or financially supporting the author(s) and/or the ongoing project.

Finally, I would like to add also a warning: “Following” a person should not develop to stalking. It is essential not to be intrusive or pushy. You will see already after a short time if the person values your contribution(s), e.g., by answering friendly or thoughtfully, accepting your PRs, etc. If you get the impression that your engagement is disruptive, then stop it immediately. Either look at the code silently without interaction or try to find another “mentor” or project to get involved.

Images in Rmarkdown Files

Fri, 07 May 2021 00:00:00 +0000

Using R chunk with `knitr`

Using R chunks with knitr has the full features as outlined in the post Images: From R Markdown to HTML format.

Example

Figure 1: Caption for this figure 1

Code in R Chunk

```
{r img-with-knitr, echo=FALSE, fig.align='center', out.width='100%', fig.cap='Caption for this figure 1'}
knitr::include_graphics("images/my-image.png")
```

Code in HTML

```
<div class="figure" style="text-align: center">
    <span id="fig:img-with-knitr"></span>
    <img src="images/my-image.png" alt="Caption for this figure 1" width="100%"/>
    <p class="caption">Figure 1: Caption for this figure 1</p>
</div>

```

CSS

div.figure {
        border: 1px;
        border-style: groove;
        box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px  rgba(0, 0, 0, 0.19);
}

p.caption {
    text-align: center;
    margin-top: -0.5rem;
    margin-bottom: 0.5rem;
    font-size: smaller;
}

Summary

Caption: yes
Format of caption: no
Caption automatically numbered: yes
Alt: yes
Title: no
Tooltip: no
Width/Height: yes
Link to: no
ID: yes (format: “fig:<chunk name>)
Classes: yes (with out.extra, example: out.extra='class="border shadowed"'
CSS style: yes (with out.extra, example: out.extra='style="background-color: #9ecff7; padding:10px; display: inline-block;"' See blog post Tips and tricks for working with images and figures in R Markdown documents
Other (key=value): no

Markdown via Addins ‘Insert Image’

The behavior is the same as in Images in .md files.

Using the RStudio Addin window without the width or height parameter it just generate markdown code. Is the width or height parameter included then HTML is generated but without div.figure and p.caption class. There is no caption visible and the CSS styling has to be done with <img> tag.

Example

You can’t use the Addins ‘Insert Image’ in Visual R Markdown mode because it protects the conversion by adding a backslash in front of the squared brackets: !\[Alt text\](images/my-image.png).

Code in markdown

The first line is the markdown code for images without width/height parameters. The second line has a width parameter.

![Alt text](images/my-image.png)
<img src="images/my-image.png" alt="Alt text" width="100%"/>

Code in HTML

The first line is the HTML code for images without width/height parameters. The second line has a width parameter.

<p><img src="images/my-image.png" alt="Alt text"></p> 
<img src="images/my-image.png" alt="Alt text" width="100%">

CSS

If the RStudio Addin window is used, then the img tag should be wrapped into a paragraph. Otherwise it would be generate a conflict with other tags related with images.

p img {
    border: 1px;
    border-style: groove;
    box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px  rgba(0, 0, 0, 0.19);
}

Summary

So – all in all – the Addins window is not very useful. The only advantage is the generation of the filepath and the copy of the image in the correct folder.

Caption: yes
Format of caption: yes
Caption automatically numbered: no
Alt: no
Title: no
Tooltip: no
Width/Height: yes
Link to: no
ID: no
Classes: no
CSS style: no
Other (key=value): no

Again the same behavior as in Images in .md files.

With a .Rmarkdown file Visual R Markdown offers only a reduced first part of the window as it is presented in an .Rmd file. In contrast to the .Rmd version it lacks the fields to add width and height parameter.

But more important: There is no caption! The text for the field ‘Caption/Alt’ includes the text only for the alt-attribute!

Example

Code in markdown

![Alt text (no caption!)](images/my-image.png "Text for title and tooltip")

Code in HTML

<p><img src="images/my-image.png" alt="Alt text (no caption!)" title="Text for title and tooltip"></p>

CSS

The same as with the RStudio Addin window.

Summary

Caption: no
Format of caption: no
Caption automatically numbered: no
Alt: no
Title: yes
Tooltip: yes
Width/Height: no
Link to: yes
ID: no
Classes: no
CSS style: no
Other (key=value): no

Hugo figure shortcut

Here again – as in the .md file – we do not need to protect the shortcode. We can insert it either via the Visual R Markdown menu Insert -> Shortcode or write the code directly into markdown.

Example

Figure 4: my title-text

Everything I said about the features of the figure shortcode in the post Images: From R Markdown to HTML format applies for .md and for .Rmarkdown files as well.

Summary

Caption: yes
Format of caption: no
Caption automatically numbered: yes (Academic theme)
Alt: yes
Title: no
Tooltip: no (zoomable)
Width/Height: yes
Link to: yes
ID: yes (Academic theme)
Classes: yes
CSS style: yes
Other (key=value): no

Results and Conclusion

Attribute	knitr	Addin	Visual	Hugo	Remark
Caption	✅	❌	❌	✅
C. format	❌ 1	❌	❌	❌ 1	1) standard = bold
C.numbered	✅	❌	❌	✅ 2	2) via ‘Academic’ theme
Alt	✅	❌	❌	✅
Title	❌	❌	✅	❌
Tooltip	❌	❌	✅	❌
Width/Height	✅	✅	❌	✅
Link to	❌	❌	✅	✅
ID	✅ 3	❌	❌	✅ 4	3) `fig:<chunk name>` 4) `figure-<caption text>` or ‘Academic’ theme
CSS	✅	❌	❌	✅
Other	❌5	❌	❌	✅ 6	1) via output chunk arbitrary HTML code! 4) `target`, `rel`, `attr`, `attrlink`

Table: Features of different method of inserting images in .Rmarkdown files converting to .markdown using Pandoc and Hugo/Goldmark.

Although both windows (Addins and Visual R Markdown windows) are not equipped with all the necessary attributes, here we have in contrast to .md files also the alternative with knitr chunks. So in way: .Rmarkdown files are the best of both worlds! (This is also true with the Table of Contents, which works here as well.)

Images in .md Files

Thu, 06 May 2021 00:00:00 +0000

Markdown via Addins ‘Insert Image’

Example

Code in markdown

The first line is the markdown code for images without width/height parameters. The second line has a width parameter.

![Alt text](images/my-image.png)
<img src="images/my-image.png" alt="Alt text" width="100%"/>

Code in HTML

The first line is the HTML code for images without width/height parameters. The second line has a width parameter.

<p><img src="images/my-image.png" alt="Alt text"></p> 
<img src="images/my-image.png" alt="Alt text" width="100%">

CSS

If the RStudio Addin window is used, then the img tag should be wrapped into a paragraph. Otherwise it would be generate a conflict with other tags related with images.

p img {
    border: 1px;
    border-style: groove;
    box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px  rgba(0, 0, 0, 0.19);
}

Summary

So – all in all – the Addins window is not very useful. The only advantage is the generation of the filepath and the copy of the image in the correct folder.

Caption: yes
Format of caption: yes
Caption automatically numbered: no
Alt: no
Title: no
Tooltip: no
Width/Height: yes
Link to: no
ID: no
Classes: no
CSS style: no
Other (key=value): no

With a .md file Visual R Markdown offers only a reduced first part of the window as it is presented in an .Rmd file. In contrast to the .Rmd version it lacks the fields to add width and height parameter.

But more important: There is no caption! The text for the field ‘Caption/Alt’ includes the text only for the alt-attribute!

Example

Code in markdown

![Alt text (no caption!)](images/my-image.png "Text for title and tooltip")

Code in HTML

<p><img src="images/my-image.png" alt="Alt text (no caption!)" title="Text for title and tooltip"></p>

CSS

The same as with the RStudio Addin window.

Summary

Caption: no
Format of caption: no
Caption automatically numbered: no
Alt: no
Title: yes
Tooltip: yes
Width/Height: no
Link to: yes
ID: no
Classes: no
CSS style: no
Other (key=value): no

Hugo figure shortcut

In contrast to the .Rmd file we do not need to protect the shortcode. We can insert it either via the Visual R Markdown menu Insert -> Shortcode or write the code directly into markdown.

Example

Figure 4: my title-text

Everything I said about the features of the figure shortcode in the post Images: From R Markdown to HTML format applies for .md files as well.

Summary

Caption: yes
Format of caption: no
Caption automatically numbered: yes (Academic theme)
Alt: yes
Title: no
Tooltip: no (zoomable)
Width/Height: yes
Link to: yes
ID: yes (Academic theme)
Classes: yes
CSS style: yes
Other (key=value): no

Results and Conclusion

Attribute	Addin	Visual	Hugo	Remark
Caption	❌	❌	✅
C. format	❌	❌	❌ 1	1) standard = bold
C.numbered	❌	❌	✅ 2	2) via ‘Academic’ theme
Alt	❌	❌	✅
Title	❌	✅	❌
Tooltip	❌	✅	❌
Width/Height	✅	❌	✅
Link to	❌	✅	✅
ID	❌	❌	✅ 3	3) `figure-<caption text>` or ‘Academic’ theme
CSS	❌	❌	✅
Other	❌	❌	✅ 4	4) `target`, `rel`, `attr`, `attrlink`

Table: Features of different method of inserting images in .md files converting with Hugo/Goldmark to HTML

Only Hugo shortcode (with ID and numbered extension by the Academic theme) is the only real choice for figures equipped with all necessary attributes and nice styled.

Images: From R Markdown to HTML format

Wed, 05 May 2021 00:00:00 +0000

Introduction

This article is the first of a series of posts to investigate methods of inserting figures into different markdown formats. The resulting code depends on how images are included and the conversion tool they have to undergo. And — at least I think — also somewhat on the theme in use. In my case it is the blog widget of the starter-academic theme.

Here I look at the process chain from Rmd via Pandoc to HTML. I will inspect inserting images with the following methods:

R chunk code via knitr::include_graphics().
‘Insert Image’ window via blogdown Addins
‘Image …’ window vial Visual R Markdown
Hugo shortcode

Of course, you can always include HTML instead of markdown code, but this case is not of interest here as there are no changes during the conversion process.

Using r chunk with `knitr`

You can include external images with the knitr function include_graphics(). There are many chunk options to specify the resulting figure, but not all are useful for external images.

Use out.width and out.height (not fig.width or fig.height, they are for R-generated plots)
Use out.extra to add CSS styles (see for details Style your image environment with CSS)
If fig.cap is provided without fig.alt, it will also function as alternative text, which is usually not desired.
Use output hooks if you want even more control.

Example

Figure 1: Caption for figure 1

The fig.align parameter generally works correctly, but not in this theme. It always centers to a 10 (instead 0f 12) column width. Left and right alignments do not work at all. I could not find and solve the problem.

Code in R Chunk

```
{r img-with-knitr, echo=FALSE, fig.align='center', out.width='50%', fig.cap='Caption for figure 1', fig.alt='Alternative text for figure 1'}
knitr::include_graphics("images/my-image.png")
```

Code in HTML

```
<div class="figure" style="text-align: center"><span id="fig:img-with-knitr"></span>
    <img src="images/my-image.png" alt="Alternative text for figure 1" width="50%">
    <p class="caption">
        Figure 1: Caption for figure 1
    </p>
</div>
```

It is a stand-alone feature of knitr to provide automatically generated figure numbers that you can reference via their id. The id is generated from the chunk name with the pattern fig:<chunk name>. The figure 1 above can be referenced with \@ref(fig:img-with-knitr). Like this:

For more details see Figure 1.

But in that case, you cannot use other methods to insert figures with numbers as knitr will not be aware of them.

The relevant selectors for CSS styles are div.figure and p.caption. We will see that these styles are consistent with all the other methods provided by RStudio windows. But Hugo’s figure shortcode uses the HTML tags figure and figcaption. In the R Markdown Coobook is a work around expained how you can produce these Hugo HTML tags with knitr.

CSS

The CSS style I have used to display the image:

img {
        border: 1px;
        border-style: groove;
        box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px  rgba(0, 0, 0, 0.19);
}

p.caption {
    text-align: center;
    margin-top: -0.5rem;
    margin-bottom: 0.5rem;
    font-size: smaller;
}

Summary

Using the knitr function include_graphics() for external images provides a rich set of image attributes (tags). It is also very flexible, especially if you are using the more complex possibilities like programming the output chunk hook.

Caption: yes
Format of caption: no
Caption automatically numbered: yes
Alt: yes
Title: no
Tooltip: no
Width/Height: yes
Link to: no
ID: yes (format: "fig:<chunk name>)
Classes: yes (with out.extra, example: out.extra='class="border shadowed"'
CSS style: yes (with out.extra, example: out.extra='style="background-color: #9ecff7; padding:10px; display: inline-block;"' See blog post Tips and tricks for working with images and figures in R Markdown documents
Other (key=value): no

Markdown via Addins ‘Insert Image’

The possibilities of RStudio Addins window for blogdown are sparse. But it has one big advantage: The addin helps user to provide the correct file path and copies the image to the right place.

The RStudio Addins window for blogdown package allows only width / height arguments and alternative text. The content of the ‘alt’-attribute is in the final HTML code converted to the caption, which is not correct:

The alternate text should describe what you can see on the image in case the image does not appear (e.g., is blocked) or the user applies a screen reader. ‘Alt’ text is also rendered by search engines. Every picture should have a corresponding ‘alt’ attribute The caption by contrast is not so important. It provides additional information and appears under the image explaining the content to reader who are able to see the picture.

Example

Figure 2: Caption for this figure 2

You can’t use the Addins ‘Insert Image’ in Visual R Markdown mode because it protects the conversion by adding a backslash in front of the squared brackets: ![Alt text](images/my-image.png).

Code in markdown

RStudio Addins window produces the following markdown code:

![**Figure 2:** Caption for this figure 2](images/my-image.png){width=100%}

I think starting with the RStudio version 1.4 (January 2021) the RStudio Addin window is superseded by the the Visual R Markdown window (see next section). If you are turning on the visual editor you can always enhance the rudimentary markdown of the addin window with all the features of Visual R Markdown.

For this improvement you need to

turn on Visual RStudio Markdown;
select the image which markdown you want to enhance;
click into the small round button with the three points to open up the dialog window;
correct or add the desired content for the attributes (there is more under the “Attributes” tab);
close the window;

If you want to work with markdown directly you may turn off Visual RStudio Markdown.

Screenshot of the Visual RStudio Markdown window

Code in HTML

Here I am referring to the RStudio Addin without enhancement from the Visual R Markdown window.

<div class="figure">
    <img src="images/my-image.png" alt="">
    <p class="caption"><strong>Figure 2:</strong> Caption for this figure 1           
    </p>
</div>

As you can see: The alt attribute is empty, although I have filled it out!

If you do not provide text for the alt (= capture) attributes then there is no div.figure and p.caption class. In this case there is only the img tag as you can see with the image under the header Markdown via Addins ‘Insert Image’.

CSS

The conversion to HTML produced exactly the same classes as in the result with the knitr image inclusion (see the CSS code under the knitr section).

Summary

Caption: yes
Format of caption: yes
Caption automatically numbered: no
Alt: no
Title: no
Tooltip: no
Width/Height: yes
Link to: no
ID: no
Classes: no
CSS style: no
Other (key=value): no

Visual R Markdown via Menu ‘Insert …’

After you have turned on Visual R Markdown you can load the image window via the Menu 'Insert ' -> 'Image…' or shortcut ⇧⌘I. For an overview I put in the picture above both parts of the window side by side. You can see that it offers a very complete list of image attributes.

If you do not include text in the “Caption/Alt” field then no HTML code for the div.figure and p.caption classes will be produced and the appropriate CSS styles cannot be applied.

Example

Figure 3: Caption for this figure

Even in this enhanced window is the wrong mixture of ‘Caption’ and ‘Alt’ attributes offered. But there is a work around with the ‘Other’-field as I have shown in the screenshot.

Fill in the field “Caption/Alt” and add the alt attribute in the field “Others”. After the conversion to HTML the former constitutes the caption and the later the alternative text.

If you click on the inserted image and call the window again, then a slightly different window appears where fields for width and height are added and can be changed. This addition appears under the image as well by just clicking on the image.

Width and height field added after the image was included into the .Rmd page

Code in markdown

![Figure 3: Caption for this figure](images/my-image.png "title text and tooltip"){#figure3 alt="here comes a description for blind people, screen readers and search engines}

In addition to the standard markdown code all the other attributes are added inside curly brackets.

Code in HTML

<div class="figure">
    <img src="images/my-image.png" title="title text and tooltip" id="figure3"
    alt="here comes a description for blind people, screen readers and search engines">
    <p class="caption">
        Figure 3: Caption for this figure
    </p>
</div>

CSS

The conversion to HTML produced exactly the same classes as in the result with the other two methods knitr image inclusion and Addins ‘Insert Image’).

Summary

Caption: yes
Format of caption: no
Caption automatically numbered: no
Alt: no
Title: yes
Tooltip: yes
Width/Height: yes
Link to: yes
ID: yes
Classes: yes
CSS style: yes
Other (key=value): yes

Hugo figure shortcut

You cannot simply write {{< shortcode >}} in R Markdown, because Pandoc is not aware of Hugo shortcodes, and may convert special characters so that Hugo can no longer recognize the shortcodes (e.g. < will be converted to <).¹

With Blackfriday as default Markdown rendering engine I used to use for shortcodes the blogdown::shortcode() function. But after Hugo v0.60 the default Markdown rendering engine changed to Goldmark. In the above quoted man page for the shortcode() function there is a also special note on this issue:

Since Hugo v0.60, Hugo has switched its default Markdown rendering engine to Goldmark. One consequence is that shortcodes may fail to render. You may enable the unsafe option in the configuration file: https://gohugo.io/getting-started/configuration-markup/#goldmark.

I couldn’t understand this remark as for me all the Hugo shortcodes works well. But to apply it more easily I use pure HTML code chunks to prevent a conversion by Pandoc. This has the advantage that I can include Hugo’s shortcode syntax without any changes.

Example

My caption text

Code in HTML chunk

```{=html}
{{< figure src="images/my-image.png" class="center" alt="My alt text" caption="My title text" id="shortcut-figure" numbered="true" >}}
```

The id and numbered attributes are not provided by but they are a feature from the academic theme.

If you do not use id explicitly then Hugo generates an ID with the “figure-” followed by the caption text (e.g., id="figure-my-caption-text").
You can see that the numbering systems starts from scratch, e.g., it does not account for the knitr chunks. The same is true vice versa.
Besides the already mentioned attributes Hugo also features target, rel and attribution (attr = text; attrlink = link).

CSS

```{=html}
<figure id="figure-shortcut-figure">
  <div class="d-flex justify-content-center">
    <div class="w-100">
        <img alt="My alt text" srcset="
               /post/images-from-rmd-to-html-format/images/my-image_huf81a7faf920bb11d47d82b059b9dc0cf_20503_1061e20606536f4413fb34665581822b.png 400w,
               /post/images-from-rmd-to-html-format/images/my-image_huf81a7faf920bb11d47d82b059b9dc0cf_20503_c4c18b47561549b1147ccf6dd152b5f0.png 760w,
               /post/images-from-rmd-to-html-format/images/my-image_huf81a7faf920bb11d47d82b059b9dc0cf_20503_1200x1200_fit_lanczos_2.png 1200w" src="/post/images-from-rmd-to-html-format/images/my-image_huf81a7faf920bb11d47d82b059b9dc0cf_20503_1061e20606536f4413fb34665581822b.png" width="754" height="226" loading="lazy" data-zoomable="" class="medium-zoom-image"></div>
  </div>
  <figcaption data-pre="Figure&nbsp;" data-post=":&nbsp;" class="numbered">
      My caption text
  </figcaption>
</figure>

```

The produced HTML is pretty complex, but here we are just interested in the two relevant tags for CSS styling: <figure> and <figcaption>. These two HTML tag are different to the code produced by other methods of inserting images. So maybe it would be a good idea to style both variants the same way.

Summary

Caption: yes
Format of caption: no
Caption automatically numbered: yes (Academic theme)
Alt: yes
Title: no
Tooltip: no (zoomable)
Width/Height: yes
Link to: yes
ID: yes (Academic theme)
Classes: yes
CSS style: yes
Other (key=value): no

Results and Conclusion

Table: Features of different method of inserting images in Rmd files converting to HTML
Attribute	knitr	Addin	Visual	Hugo	Remark
Caption	✅	✅	✅	✅
C. format	❌ ²	✅	❌	❌ ²	² standard = bold
C.numbered	✅	❌	❌	✅ ³	³ via ‘Academic’ theme
Alt	✅	❌	✅ ⁴	✅	⁴ via ‘Other’-field
Title	❌	❌	✅	❌
Tooltip	❌	❌	✅	❌
Width/Height	✅	✅	✅	✅
Link to	❌	❌	✅	✅
ID	✅ ⁵	❌	✅	✅ ⁶	⁵ `fig:<chunk name>` ⁶ `figure-<caption text>` or ‘Academic’ theme
CSS	✅	❌	✅	✅
Other	❌¹	❌	✅ ⁷	✅ ⁸	¹via output chunk arbitrary HTML code! ⁷ free choice! ⁸ `target`, `rel`, `attr`, `attrlink`

If we take into account that code produced by the RStudio Addin window can be improved at any time with the Visual R Markdown window then all the four offered methods are pretty similar. But keep in mind that advantages on the one hand are often counter acted by disadvantages on other areas. So — for instance — provides the conversion via Pandoc many advantages but looses also some features of Hugo or the applied theme.

To sum up this this little investigation I see three patterns of decisions criteria:

One big difference is the possibility to number the figures automatically. The Addin and Visual R Markdown windows do not provide this feature.
On the other hand filling in the window fields is — especially for people who are not so comfortable with HTML or Markdown code — easier.
Another decision criteria could be consistency: If you are using R chunks (which is the major reason to use the .Rmd format!) and want to be consistent throughout the file, then the decision for the knitr method is obvious.

But let’s see what the other file format are producing. For people using different methods² for their posts perhaps the comparison inside one file format is not sufficient. Perhaps there is a method not ideal when considered only one file format but has a higher consistency when looked all file format together.

Helper functions to write Hugo shortcodes using the R syntax↩︎
As with blogdown version 1.3 not all files are automatically rendered, one could choose a different file and conversion format for every post separately. This requires (1) deleting those files produced by the conversion process in the folder of the post under consideration (2) renaming the file ending of the main file and kniting/rendering the new file format again.↩︎

R Markdown | Thought splinters

Using GitHub as a Mentoring Tool

Beginner, Intermediate, and Expert Level

Project for Motivation Necessary

Looking for a Human Mentor

GitHub as a Mentoring Tool

An instructive example

Lesson learned

Looking Experts over their Shoulders

Summary

Images in Rmarkdown Files

Using R chunk with knitr

Example

Code in R Chunk

Code in HTML

CSS

Summary

Markdown via Addins ‘Insert Image’

Example

Code in markdown

Code in HTML

CSS

Summary

Visual R Markdown via Menu ‘Insert …’

Example

Code in markdown

Code in HTML

CSS

Summary

Hugo figure shortcut

Example

Summary

Results and Conclusion

Images in .md Files

Markdown via Addins ‘Insert Image’

Example

Code in markdown

Code in HTML

CSS

Summary

Visual R Markdown via Menu ‘Insert …’

Example

Code in markdown

Code in HTML

CSS

Summary

Hugo figure shortcut

Example

Summary

Results and Conclusion

Images: From R Markdown to HTML format

Introduction

Using r chunk with knitr

Example

Code in R Chunk

Code in HTML

CSS

Summary

Markdown via Addins ‘Insert Image’

Example

Code in markdown

Code in HTML

CSS

Summary

Visual R Markdown via Menu ‘Insert …’

Example

Code in markdown

Code in HTML

CSS

Summary

Hugo figure shortcut

Example

Code in HTML chunk

CSS

Summary

Results and Conclusion

Using R chunk with `knitr`

Using r chunk with `knitr`