Building page from RMarkdown

[ns-rse]

Had lots of head scratching today as to why a change to content/setup/gitkraken/_index.en.Rmd wasn't rendered in the Netlify deploy previews.

Eventually figured out that its because this is the source for content/setup/gitkraken/_index.en.html and it is the HTML file that is used in building and deployment. The RMarkdown isn't rendered automatically by Hugodown.

This is alluded to in the README.md which states...

Some Markdown content is generated with R Markdown, using hugodown.

To resolve this I attempted to build the rmarkdown::render() the .Rmd in two places.

Within content/setup/gitkraken

143.167.101.237 ❱ R -e "rmarkdown::render('_index.en.Rmd')"                                                                    
                                                                                                                               
> rmarkdown::render('_index.en.Rmd')                                                                                           
                                                                                                                               
                                                                                                                               
processing file: _index.en.Rmd                                                                                                 
                                                                                                                               
output file: _index.en.knit.md                                                                                                 
                                                                                                                               
/usr/bin/pandoc +RTS -K512m -RTS _index.en.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --ou
tput _index.en.html --lua-filter /usr/lib/R/library/rmarkdown/rmarkdown/lua/pagebreak.lua --lua-filter /usr/lib/R/library/rmark
down/rmarkdown/lua/latex-div.lua --embed-resources --standalone --variable bs3=TRUE --section-divs --template /usr/lib/R/librar
y/rmarkdown/rmd/h/default.html --no-highlight --variable highlightjs=1 --variable theme=bootstrap --mathjax --variable 'mathjax
-url=https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --include-in-header /tmp/RtmpvbfYMR/rmarkdown-
strb0e454e2935e.html                                                                                                           
pandoc: /images/gpg_off.png: openBinaryFile: does not exist (No such file or directory)                                        
Error: pandoc document conversion failed with error 1                                                                          
Execution halted                                                                                                               
Server closing... Closed.                                                                                                      

Top level of the repository

143.167.101.237 ❱ R -e "rmarkdown::render('content/setup/gitkraken/_index.en.Rmd')"    

> rmarkdown::render('content/setup/gitkraken/_index.en.Rmd')


processing file: _index.en.Rmd
                                                                                                             
output file: _index.en.knit.md

/usr/bin/pandoc +RTS -K512m -RTS _index.en.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --ou
tput _index.en.html --lua-filter /usr/lib/R/library/rmarkdown/rmarkdown/lua/pagebreak.lua --lua-filter /usr/lib/R/library/rmark
down/rmarkdown/lua/latex-div.lua --embed-resources --standalone --variable bs3=TRUE --section-divs --template /usr/lib/R/librar
y/rmarkdown/rmd/h/default.html --no-highlight --variable highlightjs=1 --variable theme=bootstrap --mathjax --variable 'mathjax
-url=https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --include-in-header /tmp/Rtmpb9EXIq/rmarkdown-
strb779402dd966.html 
pandoc: /images/gpg_off.png: openBinaryFile: does not exist (No such file or directory)
Error: pandoc document conversion failed with error 1
Execution halted
Server closing... Closed.

In both cases the failure is because /images/gpg_off.png can not be found. This file resides at /static/images/gpg_off.png.

Changing _index.en.Rmd to have the following relative path means that rmarkdown::render("_index.en.Rmd") completes successfully and the resulting HTML page has the PNG file embeded within it (i.e. not a link).

![](../../../static/images/gpg_off.png

143.167.101.237 ❱ R -e "rmarkdown::render('_index.en.Rmd')"

> rmarkdown::render('_index.en.Rmd')


processing file: _index.en.Rmd
                                                                                                            
output file: _index.en.knit.md

/usr/bin/pandoc +RTS -K512m -RTS _index.en.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --ou
tput _index.en.html --lua-filter /usr/lib/R/library/rmarkdown/rmarkdown/lua/pagebreak.lua --lua-filter /usr/lib/R/library/rmark
down/rmarkdown/lua/latex-div.lua --embed-resources --standalone --variable bs3=TRUE --section-divs --template /usr/lib/R/librar
y/rmarkdown/rmd/h/default.html --no-highlight --variable highlightjs=1 --variable theme=bootstrap --mathjax --variable 'mathjax
-url=https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' --include-in-header /tmp/Rtmpghgs77/rmarkdown-
strcc6b47d18e62.html 

Output created: _index.en.html
> 
> 
Server closing... Closed.

The README.md also mentions the R package hugodown and I played around trying to build with hugodown::build_site() without success. Not overly familiar with hugodown though, this is as far as I got...

> build_site(site="_index.en.Rmd", dest=".")
Error in `package_file()`:
! Could not find package root.
ℹ Is . inside a package?
Run `rlang::last_error()` to see where the error occurred.
> q()
Server closing... Closed.

I'm not sure whether this change should be made or not, but I do think the README.md would benefit from additional details on this so that others don't get confused should they ever edit this file in the future.

Something like...

***

### Building

It is powered by [Hugo](https://gohugo.io/) and the following themes:

* [Hugo theme learn](https://github.com/matcornic/hugo-theme-learn)
* [Hugo theme reveal-hugo](https://github.com/dzello/reveal-hugo)

Slides for each section are listed in the menu and opened in a new tab (thanks to a [custom menu
layout](/blob/master/layouts/partials/menu.html), compared to the original Hugo learn theme).


Some Markdown content is generated with [R Markdown](https://rmarkdown.rstudio.com/), using
[hugodown](https://github.com/r-lib/hugodown/).

Currently the only file `.Rmd` file is `content/setup/gikraken/_index.en.Rmd` and when this is modified the `html` file needs generating and including in the Git commit for the change to be reflected in the deployed website. This is done by running

```
<Insert description for rendering Rmd to html via rmarkdown or hugodown>
```

The website is deployed by [Netlify](https://www.netlify.com/).

Alternatively...

The use of Rmarkdown here appears to be so that the GitKraken pages can be embedded within the page. An alternative solution is to do away with the embedding and just link to the page (links are already in-place).

[EdwinB12]

To expand on Neils 'Alternatively' section, its worth pointing out that this is the only .Rmd file in the entire repository. So by removing the embedding on this one page would remove the need to support Rmd at all.

[zadrafi]

Having the same exact issue with blogdown using both Zotero or just using a bib file

[ns-rse]

This might be able to be addressed using a Hugo plugin shortcode which has been used to add a recap to the materials which @davidwilby has added. Its for Markdown but there may be an alternative for embedding HTML. See #62 and Hugo | Shortcodes.

[davidwyld]

The shortcode is, e.g.:

{{% include "/01-getting-started-with-git-and-github/00-typical-workflow.en.md" %}}

added here:
https://github.com/RSE-Sheffield/git-github-zero-to-hero/pull/62/files

[ns-rse]

@tdjames1 and I came across this again the other day when updating the links to GitKraken resources (see #129).

Solved via #130 and #131 but we should revisit whether we need to keep .Rmd files or if we can switch to using Hugo shortcodes as mentioned above.