rse-sheffield/rse-workshop-materials-template

RSE Sheffield template for Hugo & Hugodown workshop materials

Version control through Git, GitHub & GitKraken for researchers

Source of the website of a short course.

It is powered by Hugo and the following themes:

• Hugo theme learn
• Hugo theme reveal-hugo

Slides for each section are listed in the menu and opened in a new tab (thanks to a custom menu layout, compared to the original Hugo learn theme).

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

The website is deployed by Netlify.

Why these tools?

Why use Hugo for both the website and slidedecks, and not, say Hugo+hugodown for pages and xaringan for slides? This way the source of slides is html produced by Hugo from Markdown content. It allows me to use:

• downlit syntax highlighting for slides created from R Markdown with hugodown output format;
• Chroma syntax highlighting for other languages;
• emojis! :grin: works in slides;
• Shortcodes in slides, should I choose to.

Also, because slides are in the content, they are indexed by the Hugo learn theme so searchable!

Credits

The workshop materials website template is based on the hugo-theme-learn, reveal-hugo Hugo themes and further work and configuration by Maëlle Salmon for her course site on Scientific blogging with R Markdown.

Creating Content

All contect lives in the content/ folder

To create a new chapter, ideally create a new folder within content/ use

hugo new --kind chapter <chapter-folder>/_index.md

You can add further sections to the chapter with

hugo new <chapter-folder>/<section-title>.md

It is best to start the file name for new section with a zero padded number, indicating the order of the sections (for visual ordering of the files in your text editor). To set the ordering of each section in the navigation menu, use the weight argument in the YAML header of each file. Weights in the chapter YAML header specify the order of the chapters in the navigation panel while weights in normal sections refer to the internal ordering of sections within each chapter.

For more details, refer to the hugo learn theme documentation site.

rse-workshop-materials-template's Issues

Debugging set up on a mac

hugodown::hugo_locate()
#> /Users/Anna/Library/Caches/hugodown/hugo_extended_0.73.0_macOS_64bit/hugo

^{Created on 2020-09-29 by the reprex package (v0.3.0)}

devtools::session_info()
#> ─ Session info ───────────────────────────────────────────────────────────────
#>  setting  value                       
#>  version  R version 3.6.2 (2019-12-12)
#>  os       macOS Catalina 10.15.6      
#>  system   x86_64, darwin15.6.0        
#>  ui       X11                         
#>  language (EN)                        
#>  collate  en_GB.UTF-8                 
#>  ctype    en_GB.UTF-8                 
#>  tz       Europe/London               
#>  date     2020-09-29                  
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────
#>  package     * version    date       lib source                        
#>  assertthat    0.2.1      2019-03-21 [1] CRAN (R 3.6.0)                
#>  backports     1.1.10     2020-09-15 [1] CRAN (R 3.6.2)                
#>  callr         3.4.2      2020-02-12 [1] CRAN (R 3.6.0)                
#>  cli           2.0.2      2020-02-28 [1] CRAN (R 3.6.0)                
#>  crayon        1.3.4      2017-09-16 [1] CRAN (R 3.6.0)                
#>  desc          1.2.0      2018-05-01 [1] CRAN (R 3.6.0)                
#>  devtools      2.2.2      2020-02-17 [1] CRAN (R 3.6.0)                
#>  digest        0.6.25     2020-02-23 [1] CRAN (R 3.6.0)                
#>  ellipsis      0.3.1      2020-05-15 [1] CRAN (R 3.6.2)                
#>  evaluate      0.14       2019-05-28 [1] CRAN (R 3.6.0)                
#>  fansi         0.4.1      2020-01-08 [1] CRAN (R 3.6.0)                
#>  fs            1.5.0      2020-07-31 [1] CRAN (R 3.6.2)                
#>  glue          1.4.2      2020-08-27 [1] CRAN (R 3.6.2)                
#>  highr         0.8        2019-03-20 [1] CRAN (R 3.6.0)                
#>  htmltools     0.5.0      2020-06-16 [1] CRAN (R 3.6.2)                
#>  knitr         1.29       2020-06-23 [1] CRAN (R 3.6.2)                
#>  magrittr      1.5        2014-11-22 [1] CRAN (R 3.6.0)                
#>  memoise       1.1.0      2017-04-21 [1] CRAN (R 3.6.0)                
#>  pkgbuild      1.0.6      2019-10-09 [1] CRAN (R 3.6.0)                
#>  pkgload       1.0.2      2018-10-29 [1] CRAN (R 3.6.0)                
#>  prettyunits   1.1.1      2020-01-24 [1] CRAN (R 3.6.0)                
#>  processx      3.4.4      2020-09-03 [1] CRAN (R 3.6.2)                
#>  ps            1.3.4      2020-08-11 [1] CRAN (R 3.6.2)                
#>  R6            2.4.1      2019-11-12 [1] CRAN (R 3.6.0)                
#>  remotes       2.1.1      2020-02-15 [1] CRAN (R 3.6.0)                
#>  rlang         0.4.7      2020-07-09 [1] CRAN (R 3.6.2)                
#>  rmarkdown     2.3        2020-06-18 [1] CRAN (R 3.6.2)                
#>  rprojroot     1.3-2      2018-01-03 [1] CRAN (R 3.6.0)                
#>  sessioninfo   1.1.1      2018-11-05 [1] CRAN (R 3.6.0)                
#>  stringi       1.5.3      2020-09-09 [1] CRAN (R 3.6.2)                
#>  stringr       1.4.0      2019-02-10 [1] CRAN (R 3.6.0)                
#>  testthat      2.3.2      2020-03-02 [1] CRAN (R 3.6.0)                
#>  usethis       1.6.1.9000 2020-06-08 [1] Github (r-lib/usethis@b8292e6)
#>  withr         2.2.0      2020-04-20 [1] CRAN (R 3.6.2)                
#>  xfun          0.17       2020-09-09 [1] CRAN (R 3.6.2)                
#>  yaml          2.2.1      2020-02-01 [1] CRAN (R 3.6.0)                
#> 
#> [1] /Library/Frameworks/R.framework/Versions/3.6/Resources/library

^{Created on 2020-09-29 by the reprex package (v0.3.0)}

static build errors

When running hugo -D to build the static pages, the following errors are encountered:

Building sites … ERROR 2020/09/29 09:57:15 Failed to add template "partials/menu.html" in path "/home/ac1dwi/playground/rse-workshop-materials-template/layouts/partials/menu.html": template: partials/menu.html:98: unexpected "=" in operand
ERROR 2020/09/29 09:57:15 partials/menu.html : template: partials/menu.html:98: unexpected "=" in operand
ERROR 2020/09/29 09:57:15 Unable to locate template for shortcode "fragment" in page "01-getting-started/slides/index.en.md"
ERROR 2020/09/29 09:57:15 Unable to locate template for shortcode "notice" in page "setup/_index.md"
ERROR 2020/09/29 09:57:15 Unable to locate template for shortcode "notice" in page "setup/github/_index.en.md"
Total in 15 ms
Error: Error building site: logged 5 error(s)

OS: Ubuntu 18.04
Hugo version Hugo Static Site Generator v0.40.1 linux/amd64 BuildDate: 2018-04-25T17:16:11Z
Go version go version go1.10.4 linux/amd64

NOTE: this is installed via the unrecommended apt method

Write hugo command line documentation for serving site locally

Start with Hugo Getting started docs

Figure out what to do with assets