search

RSE-Sheffield / git-github-zero-to-hero

Training materials for zero to hero training in version control through git, github and gitkraken
https://srse-git-github-zero2hero.netlify.app/
17 stars 10 forks source link

Building page from RMarkdown #81

Open ns-rse opened 1 year ago

ns-rse commented 1 year ago

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
``` 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 commented 1 year ago

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 commented 1 year ago

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

ns-rse commented 1 year ago

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.

davidwilby commented 1 year ago

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