├── .gitignore ├── layouts └── partials │ ├── custom-header.html │ ├── highlight-style.html │ ├── logo.html │ ├── custom-footer.html │ ├── layout │ ├── theme.html │ └── javascript.html │ └── menu.html ├── static ├── images │ ├── favicon.png │ └── highlight.jpg ├── countdown-0.3.5 │ ├── smb_stage_clear.mp3 │ ├── countdown.css │ └── countdown.js └── css │ ├── theme-mine.css │ └── pygments.css ├── content ├── conclusion │ ├── _index.en.md │ └── slides │ │ ├── index.en.Rmd │ │ └── index.en.md ├── intro │ ├── _index.en.md │ ├── starters.en.md │ └── slides │ │ ├── index.en.Rmd │ │ └── index.en.md ├── promotion │ ├── _index.en.Rmd │ ├── _index.en.md │ ├── further-resources.en.md │ └── slides │ │ ├── index.en.Rmd │ │ └── index.en.md ├── others │ ├── _index.en.md │ ├── jekyll.en.md │ ├── diy.en.md │ ├── wix.en.md │ └── gatsby.en.md ├── noblog │ ├── _index.en.md │ ├── gistr.en.md │ └── devto.en.md ├── hugo │ ├── _index.en.Rmd │ ├── _index.en.md │ ├── demo │ │ ├── index.en.Rmd │ │ └── index.en.md │ ├── slides │ │ ├── index.en.Rmd │ │ └── index.en.md │ └── further-resources.en.md ├── reproducibility │ ├── _index.en.Rmd │ ├── _index.en.md │ ├── further-resources.en.md │ └── slides │ │ ├── index.en.Rmd │ │ └── index.en.md ├── distill │ ├── _index.en.Rmd │ ├── _index.en.md │ ├── demo │ │ ├── index.en.Rmd │ │ └── index.en.md │ ├── slides │ │ ├── index.en.Rmd │ │ └── index.en.md │ └── further-resources.en.md ├── webdev │ ├── _index.en.md │ ├── url.en.md │ ├── jamstack.en.md │ ├── css.en.md │ ├── hire.en.md │ ├── devtools.en.md │ └── playgrounds.en.md ├── wordpress │ ├── _index.en.Rmd │ ├── _index.en.md │ ├── demo │ │ ├── index.en.Rmd │ │ └── index.en.md │ ├── further-resources.en.md │ └── slides │ │ ├── index.en.Rmd │ │ └── index.en.md ├── _index.en.md ├── credits.en.md └── snippets.en.md ├── archetypes └── default.md ├── go.mod ├── test-course-site.Rproj ├── netlify.toml ├── go.sum ├── README.md └── config.toml /.gitignore: -------------------------------------------------------------------------------- 1 | .Rhistory 2 | .RData 3 | .Rproj.user 4 | node_modules 5 | public 6 | -------------------------------------------------------------------------------- /layouts/partials/custom-header.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/images/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/maelle/rmd-blogging-course/HEAD/static/images/favicon.png -------------------------------------------------------------------------------- /layouts/partials/highlight-style.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/images/highlight.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/maelle/rmd-blogging-course/HEAD/static/images/highlight.jpg -------------------------------------------------------------------------------- /content/conclusion/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Conclusion 3 | weight: 10 4 | slides: true 5 | --- 6 | 7 | Let's debrief! -------------------------------------------------------------------------------- /archetypes/default.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "{{ replace .Name "-" " " | title }}" 3 | date: {{ .Date }} 4 | draft: true 5 | --- 6 | 7 | -------------------------------------------------------------------------------- /static/countdown-0.3.5/smb_stage_clear.mp3: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/maelle/rmd-blogging-course/HEAD/static/countdown-0.3.5/smb_stage_clear.mp3 -------------------------------------------------------------------------------- /layouts/partials/logo.html: -------------------------------------------------------------------------------- 1 | 2 |

3 | -------------------------------------------------------------------------------- /content/intro/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Introduction 3 | weight: 1 4 | chapter: true 5 | slides: true 6 | menuTitle: Intro 7 | --- 8 | 9 | What do you need to know before this course? 10 | 11 | Why would you create a blog? -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module test-course-site 2 | 3 | go 1.14 4 | 5 | require ( 6 | github.com/dzello/reveal-hugo v0.0.0-20200513004858-ff9f389743ae // indirect 7 | github.com/matcornic/hugo-theme-learn v0.0.0-20200601144331-3efb32712c5c // indirect 8 | ) 9 | -------------------------------------------------------------------------------- /content/promotion/_index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Readers 3 | weight: 5 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | # Around readers 10 | 11 | A few tips about promoting your blog & interacting with readers. -------------------------------------------------------------------------------- /layouts/partials/custom-footer.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /test-course-site.Rproj: -------------------------------------------------------------------------------- 1 | Version: 1.0 2 | 3 | RestoreWorkspace: Default 4 | SaveWorkspace: Default 5 | AlwaysSaveHistory: Default 6 | 7 | EnableCodeIndexing: Yes 8 | UseSpacesForTab: Yes 9 | NumSpacesForTab: 2 10 | Encoding: UTF-8 11 | 12 | RnwWeave: Sweave 13 | LaTeX: pdfLaTeX 14 | -------------------------------------------------------------------------------- /content/promotion/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Readers 3 | weight: 5 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | rmd_hash: 0b4574a0f75ea15b 8 | 9 | --- 10 | 11 | Around readers 12 | ============== 13 | 14 | A few tips about promoting your blog & interacting with readers. 15 | 16 | -------------------------------------------------------------------------------- /content/others/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Other website generators 3 | weight: 10 4 | --- 5 | 6 | You might prefer yet another solution! 7 | Note that if you use a website generator few other R users use, 8 | there will be 9 | 10 | * less tooling to go with it now, 11 | * less tooling for Rmd content migration from it in the future. -------------------------------------------------------------------------------- /content/others/jekyll.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Jekyll 3 | weight: 5 4 | --- 5 | 6 | Use [Jekyll](https://jekyllrb.com/) if you use Ruby a lot: this way you might like it, and not be scared 7 | by the installation of gems. 8 | 9 | {{% notice info %}} 10 | Documentation of [Jekyll support in the blogdown package](https://bookdown.org/yihui/blogdown/jekyll.html). 11 | {{% /notice %}} -------------------------------------------------------------------------------- /content/noblog/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: No blog? 3 | weight: 20 4 | --- 5 | 6 | How to share content without having a blog? 7 | 8 | A downside of the solutions is that you don't own your platform. 9 | 10 | Another downside is that these are platforms for tech blogging rather than _scientific_ blogging per se. 11 | 12 | In all cases remember to promote your content, even if there is no RSS feed! -------------------------------------------------------------------------------- /netlify.toml: -------------------------------------------------------------------------------- 1 | [build] 2 | publish = "/public" 3 | command = "hugo -d public" 4 | 5 | [context.production.environment] 6 | HUGO_VERSION = "0.73.0" 7 | GO_VERSION="1.12" 8 | 9 | [context.deploy-preview.environment] 10 | HUGO_VERSION = "0.73.0" 11 | GO_VERSION="1.12" 12 | 13 | 14 | [context.branch-deploy] 15 | command = "hugo --gc -b $DEPLOY_PRIME_URL" 16 | 17 | [context.deploy-preview] 18 | command = "hugo --gc -b $DEPLOY_PRIME_URL" -------------------------------------------------------------------------------- /content/hugo/_index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Hugo 3 | weight: 3 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | We'll explore [Hugo](https://gohugo.io/documentation/) with [hugodown](https://hugodown.r-lib.org/). 10 | 11 | Note that Hugo changes fast. Exciting (more features!) and scary (broken websites). 12 | 13 | The hugodown package is itself an experimental R package, but it pins a Hugo version to projects. -------------------------------------------------------------------------------- /content/reproducibility/_index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reproducibility 3 | weight: 4 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | # Reproducibility 10 | 11 | We're all about transparency and reproducibility but are your blog posts supposed to be perfectly encapsulated reproducible analyses? 12 | 13 | Spoiler: probably not; but there are less ambitious steps that are important. 14 | Indicate session info and data origin, backup, take notes. -------------------------------------------------------------------------------- /content/hugo/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Hugo 3 | weight: 3 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | rmd_hash: b6610e2d051f0155 8 | 9 | --- 10 | 11 | We'll explore [Hugo](https://gohugo.io/documentation/) with [hugodown](https://hugodown.r-lib.org/). 12 | 13 | Note that Hugo changes fast. Exciting (more features!) and scary (broken websites). 14 | 15 | The hugodown package is itself an experimental R package, but it pins a Hugo version to projects. 16 | 17 | -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/dzello/reveal-hugo v0.0.0-20200513004858-ff9f389743ae h1:x2cMxkgkOshGVuUswcYK1Nda6s0QFff8QDOIt3eCfKA= 2 | github.com/dzello/reveal-hugo v0.0.0-20200513004858-ff9f389743ae/go.mod h1:0S5eDEdHBx8tSj8veo9lUnuJRXa8WqmpANd0Lz7CLc8= 3 | github.com/matcornic/hugo-theme-learn v0.0.0-20200601144331-3efb32712c5c h1:xPoHdfS2a/O/6q4LuhMtusqa6hP5f69d6LwiyfvkDfE= 4 | github.com/matcornic/hugo-theme-learn v0.0.0-20200601144331-3efb32712c5c/go.mod h1:YoToDcvQxmAFhpEuapKUysBDEBckqDEssqTrmeZ2+uY= 5 | -------------------------------------------------------------------------------- /content/distill/_index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Distill 3 | weight: 3 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | [Distill](rstudio.github.io/distill/) is both a framework and an R package. 10 | 11 | Its docs state: 12 | 13 | > Distill for R Markdown is a web publishing format optimized for scientific and technical communication. 14 | 15 | It has both an R Markdown output format, and handy functions such as `distill::create_post()`. 16 | 17 | Let's explore it! -------------------------------------------------------------------------------- /content/reproducibility/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reproducibility 3 | weight: 4 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | rmd_hash: f388f66391e3a783 8 | 9 | --- 10 | 11 | Reproducibility 12 | =============== 13 | 14 | We're all about transparency and reproducibility but are your blog posts supposed to be perfectly encapsulated reproducible analyses? 15 | 16 | Spoiler: probably not; but there are less ambitious steps that are important. Indicate session info and data origin, backup, take notes. 17 | 18 | -------------------------------------------------------------------------------- /content/webdev/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Web development resources 3 | menuTitle: Web dev 4 | weight: 100 5 | --- 6 | 7 | Some resources around web development that I found interesting. 8 | 9 | You might need to learn more about web development to 10 | 11 | * tweak things yourself; 12 | * learn the language of the web developer you hire. 13 | 14 | For fun, I recommend reading [the dev.to post "How to build a website in 2020"](https://dev.to/thegreengreek/how-to-build-a-website-in-2020-4f0m) ([more about dev.to as a blogging platform](/noblog/devto/)). -------------------------------------------------------------------------------- /content/webdev/url.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Domain 3 | weight: 2 4 | --- 5 | 6 | Having your own domain is in my opinion a great idea as opposed to depending on a commercial platform / your employer. 7 | 8 | + Search for "custom domain + tool you're using for deploying your website". 9 | 10 | + Follow instructions. 11 | 12 | + Be patient, there are things like caches etc. so it might take time until it works. 13 | 14 | + Read funny and useful posts like [Custom domain hosting with Github and Namecheap](https://blog.brooke.science/posts/custom-domain-hosting-with-github-and-namecheap/) -------------------------------------------------------------------------------- /content/distill/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Distill 3 | weight: 3 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | rmd_hash: eac431401cb5fb0a 8 | 9 | --- 10 | 11 | [Distill](rstudio.github.io/distill/) is both a framework and an R package. 12 | 13 | Its docs state: 14 | 15 | > Distill for R Markdown is a web publishing format optimized for scientific and technical communication. 16 | 17 | It has both an R Markdown output format, and handy functions such as [`distill::create_post()`](https://rdrr.io/pkg/distill/man/create_post.html). 18 | 19 | Let's explore it! 20 | 21 | -------------------------------------------------------------------------------- /content/noblog/gistr.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: GitHub gists 3 | weight: 7 4 | --- 5 | 6 | You can post short snippets, images, etc. to [GitHub gists](https://gist.github.com/). 7 | 8 | You can even use the [`gistr` package by Scott Chamberlain](https://docs.ropensci.org/gistr/). 9 | 10 | However contrary to dev.to gists are not really, at least in my experience, a platform where people go discover content. 11 | Therefore you might want to list gists from somewhere else. 12 | A portfolio (so a blog after all, ah! Hugo [lets you easily embed gists](https://gohugo.io/content-management/shortcodes/#gist)), a tweet (ephemerous attention). -------------------------------------------------------------------------------- /content/webdev/jamstack.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: JAMStack 3 | weight: 60 4 | --- 5 | 6 | [JAMStack](https://jamstack.org/) (JavaScript, APIs, Markup) is a way to build website created & promoted by the company Netlify. 7 | From what I understand all three things shown in this course are more or less JAMStack (WordPress is not a part of the JAMStack but I've seen WordPress REST API [called "headless WordPress" and classified as JAMStack CMS](https://jamstack.wtf/#cms) :shrug:) 8 | 9 | You might find [jamstack.org](https://jamstack.org) and [jamstack.wtf](https://jamstack.wtf/) interesting for your own learning or for better interacting with web developers you might hire. -------------------------------------------------------------------------------- /content/webdev/css.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: CSS 3 | weight: 5 4 | --- 5 | 6 | [An allegory for my tweaking CSS](https://www.theguardian.com/artanddesign/2020/jun/22/experts-call-for-regulation-after-latest-botched-art-restoration-in-spain) :grin: 7 | 8 | More seriously, I'm linking to good resources I have clearly not explored enough yet. :grimacing: 9 | 10 | {{< tweet 1278052903744344064 >}} 11 | 12 | * [Learn to style HTML using CSS](https://developer.mozilla.org/en-US/docs/Learn/CSS) 13 | 14 | * [CSS-Tricks](https://css-tricks.com/) 15 | 16 | * [Resilient CSS YouTube series by Jen Simmons](https://www.youtube.com/watch?v=u00FY9vADfQ) 17 | 18 | {{< tweet 1245391028795965442 >}} 19 | 20 | -------------------------------------------------------------------------------- /content/webdev/hire.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Not yourself? 3 | weight: 2 4 | --- 5 | 6 | In the intro I mentioned that your blogging framework should be either fit in your workflow or use tools that you want to invest time in. 7 | 8 | If you want tweaks compared to default themes, you might need to hire a web developer / designer. 9 | There are also companies providing themes with support (so not tweaked). 10 | 11 | I'm not advertising for anything in particular, just reminding you that time is money or at least a finite resource. :wink: 12 | 13 | I don't have good tips for how to choose a web development company/person apart from knowing what you want and need (if you know Hugo templating, maybe you just need HTML+JS+CSS, for instance). -------------------------------------------------------------------------------- /content/noblog/devto.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: dev.to 3 | weight: 5 4 | --- 5 | 6 | [Some](https://twitter.com/_ColinFay/status/1260580782181056514) [folks](https://twitter.com/juliasilge/status/1260580363971317765) with a blog use [dev.to](https://dev.to/) to _repost_ their content from their RSS feed. 7 | 8 | You could also use your [dev.to](https://dev.to/faq) profile as your only medium! 9 | 10 | Dave Parr wrote a blog post [Posting from .Rmd to dev.to](https://dev.to/daveparr/posting-from-rmd-to-dev-to-5gld) and an [**R package** to help you post from Rmd to dev.to](https://github.com/DaveParr/dev.to.ol)! 11 | 12 | Dave Parr also wrote an exciting post ["I made my dev.to content into a website to find a new job"](https://dev.to/daveparr/i-made-my-dev-to-content-into-a-website-to-find-a-new-job-2kn5). -------------------------------------------------------------------------------- /content/wordpress/_index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: WordPress 3 | weight: 3 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | # WordPress 10 | 11 | First of all, no shame! 12 | 13 | `r hugodown::embed_tweet("1259058742513012736")` 14 | 15 | ## Our challenge 16 | 17 | How to publish your R Markdown posts to a WordPress website without copy-pasting?[^cp] 18 | 19 | The only modern solution is to my knowledge, my [own WIP package `goodpress`](https://github.com/maelle/goodpress). I'll explain a few setup steps on your website, and how to organize your posts to publish them with `goodpress::wp_post()`, if you're brave enough for using my tool. :wink: 20 | 21 | [^cp]: Copy-pasting is ok, [the pros do it](https://twitter.com/gvwilson/status/1274324689322741760); it's just not the vibe of this course. -------------------------------------------------------------------------------- /content/others/diy.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Build your own site generator? 3 | menuTitle: DIY 4 | weight: 100 5 | --- 6 | 7 | Now say that like my colleague Mark you like programming and find a website framework that you like. 8 | 9 | How about building your own site generator? 10 | 11 | Read [how Mark created his own R-based site generator using Zurb Foundation as a powerful templating tool](https://mpadge.github.io/blog/blog001.html). 12 | 13 | For further inspiration, since the distill package is also an R-based site generator, you could have a look at [its source](http://github.com/rstudio/distill), in particular how it makes the most of [R Markdown websites](https://bookdown.org/yihui/rmarkdown/rmarkdown-site.html). You could also inspect the [pull request that added an R Markdown site generator for hugodown sites to hugodown](https://github.com/r-lib/hugodown/pull/52). 14 | -------------------------------------------------------------------------------- /content/webdev/devtools.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: DevTools 3 | weight: 7 4 | --- 5 | 6 | In the distill demo if all goes well I'll have shown the web developer console in Firefox. 7 | Chrome has a web developer console too. 8 | 9 | Here are more resources about it thanks to [Bob Rudis](https://twitter.com/hrbrmstr/status/1272484048980578307) and [timelyportfolio](https://twitter.com/timelyportfolio/status/1272500040637059072) 10 | 11 | * [Official Google DevTools Docs](https://developers.google.com/web/tools/chrome-devtools/) 12 | 13 | * [Khan Academy](https://khanacademy.org/computing/computer-programming/html-css/web-development-tools/a/using-the-browser-developer-tools) 14 | 15 | * [Lifewire DevTools How-To](https://lifewire.com/web-browser-developer-tools-3988965) 16 | 17 | * [Designing in the Browser](https://www.youtube.com/playlist?list=PLNYkxOF6rcIDI0QtJvW6vKonTxn6azCsD) -------------------------------------------------------------------------------- /content/others/wix.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Wix, Squarespace? 3 | menuTitle: Wix &co 4 | weight: 200 5 | --- 6 | 7 | What about other services for building websites like Wix? 8 | 9 | First, be careful you can export your content safely and easily before you commit to a website service. 10 | 11 | Now for being able to use a workflow like the one we introduced with [`goodpress` for WordPress](https://github.com/maelle/goodpress/) you need 12 | 13 | * the service to provide an API for publishing new posts and managing media (listing, deleting, uploading); 14 | 15 | * to know what format the R Markdown output should have. 16 | 17 | Then you'd need to write a script/package around that, using HTTP packages, rmarkdown, Pandoc, etc. 18 | 19 | OR you could figure out what R Markdown output format to use and copy-paste to the post editor, and upload media by hand + tweak references to media path in the output. -------------------------------------------------------------------------------- /content/reproducibility/further-resources.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: More about reproducibility 3 | menuTitle: Further resources 4 | weight: 50 5 | --- 6 | 7 | Not specific to blogging. 8 | 9 | + [Reproducible Research Data & Project Management in R](https://annakrystalli.me/rrresearchACCE20/) 10 | 11 | + [A guide to modern reproducible data science with R](https://rstudio.com/resources/rstudioconf-2019/a-guide-to-modern-reproducible-data-science-with-r-karthik-ram/) 12 | 13 | + [A guide to reproducible code, British Ecological Society](http://www.britishecologicalsociety.org/wp-content/uploads/2017/12/guide-to-reproducible-code.pdf) 14 | 15 | + [How to Make a Reproducible Paper - slides](https://bit.ly/repro_vid), [code](https://github.com/ablucher/Workshop_ReproduciblePaper) 16 | 17 | + [How to make a reproducible version of your R analysis that can be run in a web browser](https://www.youtube.com/watch?v=wSkheV-Uqq4&feature=youtu.be) -------------------------------------------------------------------------------- /content/wordpress/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: WordPress 3 | weight: 3 4 | chapter: true 5 | slides: true 6 | output: hugodown::md_document 7 | rmd_hash: b6188ee88187119c 8 | 9 | --- 10 | 11 | WordPress 12 | ========= 13 | 14 | First of all, no shame! 15 | 16 | {{< tweet 1259058742513012736 >}} 17 | 18 | Our challenge 19 | ------------- 20 | 21 | How to publish your R Markdown posts to a WordPress website without copy-pasting?[^1] 22 | 23 | The only modern solution is to my knowledge, my [own WIP package `goodpress`](https://github.com/maelle/goodpress). I'll explain a few setup steps on your website, and how to organize your posts to publish them with [`goodpress::wp_post()`](https://rdrr.io/pkg/goodpress/man/wp_post.html), if you're brave enough for using my tool. :wink: 24 | 25 | [^1]: Copy-pasting is ok, [the pros do it](https://twitter.com/gvwilson/status/1274324689322741760); it's just not the vibe of this course. 26 | 27 | -------------------------------------------------------------------------------- /content/wordpress/demo/index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Notes from the demo 3 | menuTitle: Demo 4 | weight: 5 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | - setup (on the WordPress side, in .Renviron) was discussed on the slides, see [goodpress setup vignette](https://maelle.github.io/goodpress/articles/setup.html) 10 | 11 | - install the remotes package, `install.packages("remotes")` 12 | 13 | - install the goodpress package, `remotes::install_github("maelle/goodpress", ref = "main")` 14 | 15 | - create a folder, possibly a subfolder in a folder called "my-wordpress-posts" or so, "2020-07-03-cool-post". 16 | 17 | - in that folder, create index.Rmd. 18 | 19 | - in index.Rmd, paste [example content](/snippets/#goodpress-post). look at the YAML field, see also [goodpress usage vignette](https://maelle.github.io/goodpress/articles/goodpress.html) 20 | 21 | - knit. 22 | 23 | - use `goodpress::wp_post("2020-07-03-cool-post")` -------------------------------------------------------------------------------- /content/_index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Scientific Rmd Blogging" 3 | --- 4 | 5 | # Scientific Blogging with R Markdown 6 | 7 | Are you an R user who works in science? Would you like sharing more 8 | online? How about starting a new blog, with R Markdown (Rmd)? 9 | 10 | In this 11 | 2-hour course with live coding, we'll go on three short adventures: 12 | 13 | - setting up a scientific Rmd blog with the Distill framework and the 14 | distill package 15 | 16 | - setting up a scientific Rmd blog with the Hugo website generator and 17 | the hugodown package 18 | 19 | - adding Rmd posts to a Wordpress blog. 20 | 21 | We'll prepare for the adventures by defining what we expect of an Rmd blog. 22 | We'll end the course by reflecting on each adventure as well as 23 | mentioning important future paths such as how to promote your blog. 24 | You should leave the course ready to start a scientific R Markdown blog 25 | with your tool of choice, and knowing where to find more resources and help. -------------------------------------------------------------------------------- /content/webdev/playgrounds.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Playgrounds 3 | weight: 55 4 | --- 5 | 6 | With web development as with many other things being able to experiment increases your chance to solve a problem, like [reprex](https://reprex.tidyverse.org/) for R. 7 | 8 | * Create a new distill/Hugo website and play in it. You might like this [Lorem Ipsum Hugo shortcode](https://www.giffgaff.io/tech/lorem-ipsum-shortcode-for-hugo/). 9 | 10 | * Create a free wordpress.com website (with which you cannot use goodpress, though), or some other sort of throw away Wordpress instance. 11 | 12 | * For HTML+JS+CSS independently from website generation, use a code playground such as [CodePen](https://codepen.io/) (or [build your own for blog posts](https://masalmon.eu/2020/04/21/css-snippet/) :smile_cat:). 13 | 14 | * For sketching layouts apart from drawing on paper :grin: there are tools like [Figma](https://www.figma.com/) (that has a free version) and [Sketch](https://www.sketch.com/) (macOS only, no free version). -------------------------------------------------------------------------------- /content/intro/starters.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Before blogging 3 | weight: 5 4 | --- 5 | 6 | * In this course I expect some familiarity with R Markdown. Only the basics, some of you discovered R Markdown _yesterday_! 7 | 8 | * I use the usethis package a lot :robot: :sparkles:, and recommend doing so. Follow [usethis setup article](https://usethis.r-lib.org/articles/articles/usethis-setup.html) in particular [_"Use usethis or devtools in interactive work"_](https://usethis.r-lib.org/articles/articles/usethis-setup.html#use-usethis-or-devtools-in-interactive-work-1) and the Git/GitHub stuff. 9 | 10 | * If you use GitLab, not GitHub, you can follow [Heidi Seibold's instructions _"Setup Git RStudio GitLab"_](https://gitlab.com/HeidiSeibold/setup-git-rstudio-gitlab). There is no helper similar to `usethis::use_github()` to my knowledge. 11 | 12 | * You should be able to follow the course and manage a blog without any git knowledge. Now for later, if you feel curious about version control, I'd recommend checking out [happygitwithr.com](https://happygitwithr.com/) and [Suzan Baert's blog post about git](https://suzan.rbind.io/2018/03/reflections-4-months-of-github/). -------------------------------------------------------------------------------- /content/wordpress/demo/index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Notes from the demo 3 | menuTitle: Demo 4 | weight: 5 5 | slides: true 6 | output: hugodown::md_document 7 | rmd_hash: af15b37e8ed932b0 8 | 9 | --- 10 | 11 | - setup (on the WordPress side, in .Renviron) was discussed on the slides, see [goodpress setup vignette](https://maelle.github.io/goodpress/articles/setup.html) 12 | 13 | - install the remotes package, [`install.packages("remotes")`](https://rdrr.io/r/utils/install.packages.html) 14 | 15 | - install the goodpress package, [`remotes::install_github("maelle/goodpress", ref = "main")`](https://remotes.r-lib.org/reference/install_github.html) 16 | 17 | - create a folder, possibly a subfolder in a folder called "my-wordpress-posts" or so, "2020-07-03-cool-post". 18 | 19 | - in that folder, create index.Rmd. 20 | 21 | - in index.Rmd, paste [example content](/snippets/#goodpress-post). look at the YAML field, see also [goodpress usage vignette](https://maelle.github.io/goodpress/articles/goodpress.html) 22 | 23 | - knit. 24 | 25 | - use [`goodpress::wp_post("2020-07-03-cool-post")`](https://maelle.github.io/goodpress//reference/wp_post.html) 26 | 27 | -------------------------------------------------------------------------------- /content/credits.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Credits 3 | disableToc: true 4 | --- 5 | 6 | Thank you! 7 | 8 | ## Funding 9 | 10 | The first version of this workshop is supported by the German Federal Ministry of Education and Research as part of [a series of 3 workshops on research data management](https://wiho-fdm.github.io/). 11 | 12 | ## Hugo experts 13 | 14 | Fellow Hugo fans, who taught me a lot via their public materials and useful convos! 15 | 16 | * [Alison Hill](https://alison.rbind.io/) -- see for instance [her webinar with Desirée De Leon about "Sharing on Short Notice"](https://education.rstudio.com/blog/2020/04/sharing-on-short-notice/) 17 | * [Steph Locke](https://twitter.com/TheStephLocke) 18 | * [Lukas Burk](https://blog.jemu.name/) 19 | 20 | ## Wordpress expert 21 | 22 | * [Sébastien Rochette](https://statnmap.com/) who answered [Wordpress questions](https://twitter.com/ma_salmon/status/1263448146610438145) and actually also helped me with Hugo, directly, and [indirectly](https://github.com/matcornic/hugo-theme-learn/issues/187#issuecomment-461173989). 23 | 24 | ## Tooling 25 | 26 | * [Netlify](https://www.netlify.com) - Continuous deployement and hosting of this documentation 27 | * [Hugo](https://gohugo.io/) 28 | * [Hugo theme learn](https://github.com/matcornic/hugo-theme-learn) 29 | * [Hugo theme reveal-hugo](https://github.com/dzello/reveal-hugo) 30 | * [hugodown](https://github.com/r-lib/hugodown/) 31 | -------------------------------------------------------------------------------- /content/others/gatsby.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Gatsby 3 | weight: 55 4 | --- 5 | 6 | Hugo is powered by Go, Jekyll by Ruby, [Gatsby](https://www.gatsbyjs.org/) by React. 7 | Gatsby lets you use GraphQL to flexibly render your content (a special listing page for instance). 8 | So if you like either React or GraphQL or want to learn them, check out Gatsby! 9 | 10 | {{% notice info %}} 11 | Robert Myles wrote a [tool for .Rmd to .mdx](https://github.com/RobertMyles/writeMDX), 12 | introduced in the blog post [From R to Gatsby](https://www.robertmylesmcdonnell.com/content/posts/rtogatsby/). [Source of Robert Myles' website](https://github.com/RobertMyles/site). 13 | {{% /notice %}} 14 | 15 | Example of other websites: 16 | 17 | * [ggplot2tor](https://ggplot2tor.com/) 18 | 19 | * [Krist Wongsuphasawat's website](https://kristw.yellowpigz.com/) 20 | 21 | * [Ben Lindsay's website](https://benjlindsay.com/) 22 | 23 | * [Neal Grantham's website](https://www.nsgrantham.com/) 24 | 25 | * [openFDA](https://open.fda.gov/), [source](https://github.com/FDA/open.fda.gov) 26 | 27 | Not R related but interesting read: [Migrating to Gatsby](https://czep.net/20/gatsby-migration.html) by Scott Czepiel. 28 | 29 | Last point, I read in a [post on RStudio Education blog](https://education.rstudio.com/blog/2020/05/teach-interactive-course/) that Gatsby is part of what powers [the course framework created by Ines Montani](https://github.com/ines/course-starter-r). -------------------------------------------------------------------------------- /content/wordpress/further-resources.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: More about WordPress & goodpress 3 | menuTitle: Further resources 4 | weight: 50 5 | --- 6 | 7 | ## Read the manual :wink: 8 | 9 | * [goodpress docs](https://maelle.github.io/goodpress/) 10 | 11 | * Read about WordPress in your usual WordPress channels. 12 | And contribute good WordPress general resources to this repo. :wink: 13 | 14 | It's good to know how your website infrastructure evolves and works. 15 | 16 | ## Follow development :eyes: and contribute to goodpress&pressur! 17 | 18 | I have shown all there is to [`goodpress`](https://github.com/maelle/goodpress), if you want more you might contribute 19 | 20 | * with bug reports, feature requests; 21 | 22 | * with code and docs. 23 | 24 | I'd be glad to help you with R package development tips if you feel you're a n00b. 25 | 26 | Also follow [pressur development](https://github.com/hrbrmstr/pressur)! 27 | 28 | ## Where to get help? :wave: 29 | 30 | * [goodpress issue tracker](https://github.com/maelle/goodpress/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) 31 | 32 | * About WordPress itself, [WordPress forums](https://wordpress.org/support/forums/) 33 | 34 | ## Migrate your content to a static website? 35 | 36 | No judgement on your using WordPress, of course! Keep going! :rocket: 37 | 38 | But now that your posts are neatly organized in folders they'd be easier to migrate than if they were scattered. 39 | Hugo docs in particular have [a section about migrating to Hugo from WordPress](https://gohugo.io/tools/migrations/). -------------------------------------------------------------------------------- /content/reproducibility/slides/index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | outputs: 3 | - Reveal 4 | title: Workflows 5 | hidden: true 6 | layout: list 7 | weight: 1 8 | output: hugodown::md_document 9 | --- 10 | 11 | # Reproducibility? 12 | 13 | Should your blog posts still be "knittable?" 14 | 15 | --- 16 | 17 | # Reproducibility? 18 | 19 | * Be able to update your post short/medium term 20 | 21 | * Same for readers except for private data 22 | 23 | {{% fragment %}} 24 |
25 | But blog posts will **age**, which is fine, a blog is not a current docs website. 26 | {{% /fragment %}} 27 | 28 | --- 29 | 30 | # All posts 31 | 32 | Need to re-knit posts for migration, tool updates? 33 | 34 | {{% fragment %}} 35 | Or use the R Markdown output after a point (.md), potentially with YAML/other tweaks. 36 | 37 | When I migrated from Jekyll to Hugo I used the .md, not .Rmd. 38 | {{% /fragment %}} 39 | 40 | --- 41 | 42 | # Evergreen posts 43 | 44 | If you want a tutorial to be evergreen you'll need to ensure it works with the latest packages etc. 45 | 46 | But are tutorials like package vignettes? 47 | 48 | --- 49 | 50 | # Reproducible analyses 51 | 52 | How to archive your computing environment? 53 | 54 | It might be "easier" to archive the analysis elsewhere (tools for scientific articles) and link to that from the blog post. 55 | 56 | --- 57 | 58 | # Transparency 59 | 60 | For you, for readers. 61 | 62 | * Add session info to bottom of posts 63 | 64 | * Mention data origin (URL to data?) 65 | 66 | --- 67 | 68 | # Common sense 69 | 70 | * Backup 71 | 72 | * Make note of anything that might be tricky (dev version of a package) 73 | 74 | --- 75 | 76 | # What's your own take? 77 | 78 | -------------------------------------------------------------------------------- /static/countdown-0.3.5/countdown.css: -------------------------------------------------------------------------------- 1 | .countdown { 2 | background: inherit; 3 | position: absolute; 4 | cursor: pointer; 5 | font-size: 3em; 6 | line-height: 1; 7 | border-color: #ddd; 8 | border-width: 3px; 9 | border-style: solid; 10 | border-radius: 15px; 11 | box-shadow: 0px 4px 10px 0px rgba(50, 50, 50, 0.4); 12 | -webkit-box-shadow: 0px 4px 10px 0px rgba(50, 50, 50, 0.4); 13 | margin: 0.6em; 14 | padding: 10px 15px; 15 | text-align: center; 16 | } 17 | .countdown { 18 | display: flex; 19 | align-items: center; 20 | justify-content: center; 21 | } 22 | .countdown .countdown-time { 23 | background: none; 24 | font-size: 100%; 25 | padding: 0; 26 | } 27 | .countdown-digits { 28 | color: inherit; 29 | } 30 | .countdown.running { 31 | border-color: #3C9A5F; 32 | background-color: #43AC6A; 33 | } 34 | .countdown.running .countdown-digits { 35 | color: #102B1A; 36 | } 37 | .countdown.finished { 38 | border-color: #D83A20; 39 | background-color: #F04124; 40 | } 41 | .countdown.finished .countdown-digits { 42 | color: #3C1009; 43 | } 44 | .countdown.running.warning { 45 | border-color: #CFAE24; 46 | background-color: #E6C229; 47 | } 48 | .countdown.running.warning .countdown-digits { 49 | color: #39300A; 50 | } 51 | 52 | @-webkit-keyframes blink { 53 | from {opacity: 1} 54 | 50% {opacity: 0.1} 55 | to {opacity: 1} 56 | } 57 | 58 | @keyframes blink { 59 | from {opacity: 1} 60 | 50% {opacity: 0.1} 61 | to {opacity: 1} 62 | } 63 | 64 | .countdown.running.blink-colon .countdown-digits.colon { 65 | -webkit-animation: blink 2s steps(1, end) 0s infinite; 66 | animation: blink 2s steps(1, end) 0s infinite; 67 | } 68 | -------------------------------------------------------------------------------- /content/distill/demo/index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Notes from the demo 3 | menuTitle: Demo 4 | weight: 5 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | - show the RStudio IDE, ask whether anyone is unfamiliar with it. 10 | 11 | - install the distill package, `install.packages("distill")` 12 | 13 | - create blog (from RStudio Create New Project, not `distill::create_blog()`). 14 | 15 | - what's in the folder now? 16 | 17 | - show website in local browser. 18 | 19 | - `usethis::use_git()` 20 | 21 | - change site but not URL, and about. change citations: true!!! 22 | 23 | - rebuild the site via RStudio build button or `rmarkdown::render_site()`. 24 | 25 | - show website in local browser. 26 | 27 | - edit and knit welcome. including author info!! 28 | 29 | - look what changed, commit 30 | 31 | - show website in local browser. 32 | 33 | - look at post html in _posts and _site. mention navbar 34 | 35 | - commit 36 | 37 | - add a post with `distill::create_post()`. knit, look what changed this time. 38 | 39 | - add references 40 | 41 | - add latex, mention JavaScript 42 | 43 | - add footnote and aside 44 | 45 | - put website online via Netlify drag and drop. 46 | 47 | - add base_url to site config, show citations metadata is added. 48 | 49 | - Netlify drag and drop. 50 | 51 | - Some minimal styling. Introduce the web developer console. 52 | 53 | - Netlify drag and drop 54 | 55 | - GitHub repo `usethis::use_github()` 56 | 57 | - mention git checkout -b and [the distill docs about blog post workflows](https://rstudio.github.io/distill/blog_workflow.html). 58 | 59 | - Other options for deployment (Netlify link to repo, [distill docs](https://rstudio.github.io/distill/publish_website.html)) 60 | 61 | - add Twitter&GitHub -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # Scientific blogging with R Markdown 3 | 4 | 5 | [![Netlify Status](https://api.netlify.com/api/v1/badges/87a90f80-f65e-4bac-9e50-2ffa6ab8936a/deploy-status)](https://app.netlify.com/sites/scientific-rmd-blogging/deploys) 6 | [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) 7 | 8 | 9 | Source of the website of a short course. 10 | 11 | It is powered by [Hugo](https://gohugo.io/) and the following themes: 12 | 13 | * [Hugo theme learn](https://github.com/matcornic/hugo-theme-learn) 14 | * [Hugo theme reveal-hugo](https://github.com/dzello/reveal-hugo) 15 | 16 | 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). 17 | 18 | Some Markdown content is generated with [R Markdown](https://rmarkdown.rstudio.com/), using [hugodown](https://github.com/r-lib/hugodown/). 19 | 20 | The website is deployed by [Netlify](https://www.netlify.com/). 21 | 22 | Slides could be printed to PDF using Decktape which I [have done in a concept](https://github.com/maelle/test-course-site) but I am not pursuing it further. 23 | 24 | ### Why these tools? 25 | 26 | Why use Hugo for both the website and slidedecks, and not, say Hugo+hugodown for pages and xaringan for slides? 27 | This way the source of slides is html produced by Hugo from Markdown content. 28 | It allows me to use: 29 | 30 | * downlit syntax highlighting for slides created from R Markdown with hugodown output format; 31 | * Chroma syntax highlighting for other languages; 32 | * emojis! `:grin:` works in slides; 33 | * Shortcodes in slides, should I choose to. 34 | 35 | Also, because slides are in the content, they are indexed by the Hugo learn theme so searchable! 36 | 37 | -------------------------------------------------------------------------------- /content/promotion/further-resources.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: More about readers 3 | menuTitle: Further resources 4 | weight: 50 5 | --- 6 | 7 | ## Promotion 8 | 9 | * [My blog post "Get on your soapbox! R blog content and promotion"](https://masalmon.eu/2018/07/16/soapbox/) 10 | 11 | * [How to have (my) content shared by R Weekly?](https://github.com/rweekly/rweekly.org#how-to-have-my-content-shared-by-r-weekly) 12 | 13 | * Look into how to add a (category specific) RSS feed to your blog, if there's not one by default. For R Bloggers, that feed needs to feature the full content of posts. 14 | 15 | ## Comments 16 | 17 | * [My blog post about utteranc.es](https://masalmon.eu/2019/10/02/disqus/) (which means you need to use GitHub...) 18 | 19 | * [Schnack, a simple Disqus-like drop-in commenting system written in JavaScript.](https://github.com/schn4ck/schnack) read about [in a post of Noam Ross'](https://www.noamross.net/2019/08/09/a-new-website/) 20 | 21 | * Not very recent but useful [ Blog comment systems: Disqus alternatives](https://fedidat.com/530-blog-comments/) 22 | 23 | * In WordPress, built-in. 24 | 25 | 26 | ## Citations 27 | 28 | * [Hugo template for adding citation metadata to posts by Sébastien Rochette](https://github.com/statnmap/hugo-statnmap-theme/blob/3e2a54a9836fdd65779865e91058ba304b628336/layouts/partials/citation.html) 29 | 30 | * [DOI for blog posts?](https://blog.datacite.org/schema-org-register-dois/) 31 | 32 | ## Analytics 33 | 34 | If you use another service than Google Analytics, I'd be glad to hear about your experience. 35 | 36 | ## Negative feedback 37 | 38 | * The topic of negative feedback is mentioned in [The Ladybug podcast about Blogging](https://www.ladybug.dev/episodes/blogging-101?rq=blogging) 39 | 40 | * Twitter [soft block](https://www.urbandictionary.com/define.php?term=Soft%20Block). You can also _mute_ accounts. 41 | 42 | * When you are wrong, don't get defensive. Thread below. 43 | 44 | {{< tweet 1275485736259792898 >}} 45 | -------------------------------------------------------------------------------- /content/conclusion/slides/index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | outputs: 3 | - Reveal 4 | title: Conclusion 5 | hidden: true 6 | layout: list 7 | weight: 1 8 | output: hugodown::md_document 9 | --- 10 | 11 | # Scientific blogging with R Markdown 12 | 13 | :sob: Nearly time to say goodbye! 14 | 15 | --- 16 | 17 | * distill: perfect, not flexible 18 | 19 | * Hugo&hugodown: very flexible (too flexible?), changes fast, experimental R package 20 | 21 | * WordPress&goodpress: also flexible, even more experimental R package 22 | 23 | --- 24 | 25 | # What to choose 26 | 27 | * distill 28 | 29 | * Hugo Academic with `hugodown::create_site_academic()` 30 | 31 | * WordPress if you already use WordPress? 32 | 33 | --- 34 | 35 | # What to choose 36 | 37 | Start by playing! Don't commit right away. 38 | 39 | Does any of you want to say what they'd choose and why? 40 | 41 | --- 42 | 43 | # True for all 44 | 45 | * Read the docs and follow development! :eyes: 46 | 47 | * Backup! :warning: 48 | 49 | --- 50 | 51 | # Change your mind? 52 | 53 | * Migration tools 54 | 55 | * `yaml`, `commonmark` packages, etc. 56 | 57 | * Redirects! URLs are important. 404 page. 58 | 59 | --- 60 | 61 | # Have fun! 62 | 63 | If you're worried about blogging, find a blogging buddy to read your drafts? 64 | 65 | Make efforts but don't be perfectionist. 66 | 67 | --- 68 | 69 | # Setup is not fun 70 | 71 | * With R helper packages, setup is smoother 72 | 73 | * But in general setup = learning a new thing, hard but then you get used to it! 74 | 75 | --- 76 | 77 | # Regular blogging? 78 | 79 | No you don't have to unless you call your blog "the daily blog" or so. :wink: 80 | 81 | Only write if you enjoy it! Your blog can be a portfolio/news board only. 82 | 83 | --- 84 | 85 | # Tell me 86 | 87 | * Questions this afternoon :raising_hand: 88 | 89 | * Issues in the [website repo](https://github.com/maelle/rmd-blogging-course/issues) for questions :raising_hand: 90 | 91 | * [Tweets](https://twitter.com/ma_salmon)/emails to show me your websites. :star: 92 | -------------------------------------------------------------------------------- /config.toml: -------------------------------------------------------------------------------- 1 | baseURL = "https://scientific-rmd-blogging.netlify.app/" 2 | languageCode = "en-US" 3 | defaultContentLanguage = "en" 4 | title = "Scientific Rmd Blogging" 5 | enableEmoji = true 6 | pygmentsUseClasses=true 7 | ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$", "index\\.html", '\.knit\.md$', '\.utf8\.md$'] 8 | 9 | [module] 10 | [[module.imports]] 11 | path = "github.com/matcornic/hugo-theme-learn" 12 | [[module.imports]] 13 | path = "github.com/dzello/reveal-hugo" 14 | 15 | [outputFormats.Reveal] 16 | baseName = "index" 17 | mediaType = "text/html" 18 | isHTML = true 19 | 20 | 21 | [outputs] 22 | home = [ "HTML", "RSS", "JSON"] 23 | 24 | [Languages] 25 | [Languages.en] 26 | title = "Scientific Rmd Blogging" 27 | weight = 1 28 | languageName = "English" 29 | 30 | [[Languages.en.menu.shortcuts]] 31 | name = " GitHub repo" 32 | identifier = "ds" 33 | url = "https://github.com/maelle/rmd-blogging-course" 34 | weight = 10 35 | 36 | [[Languages.en.menu.shortcuts]] 37 | name = " Snippets" 38 | url = "/snippets" 39 | weight = 20 40 | 41 | [[Languages.en.menu.shortcuts]] 42 | name = " Credits" 43 | url = "/credits" 44 | weight = 30 45 | 46 | [[Languages.en.menu.shortcuts]] 47 | name = " CC-BY Licence" 48 | url = "https://creativecommons.org/licenses/by/4.0/" 49 | weight = 40 50 | 51 | [params] 52 | editURL = "https://github.com/maelle/rmd-blogging-course/edit/main/content/" 53 | description = "Scientific Rmd Blogging" 54 | author = "Maëlle Salmon" 55 | showVisitedLinks = true 56 | disableBreadcrumb = false 57 | disableNextPrev = false 58 | themeVariant = "mine" 59 | 60 | 61 | 62 | [markup] 63 | [markup.goldmark] 64 | [markup.goldmark.renderer] 65 | unsafe = true 66 | 67 | [params.reveal_hugo] 68 | theme = "white" 69 | load_default_plugins = false 70 | plugins = [ 71 | "reveal-js/plugin/zoom-js/zoom.js", 72 | "reveal-js/plugin/notes/notes.js", 73 | ] 74 | -------------------------------------------------------------------------------- /layouts/partials/layout/theme.html: -------------------------------------------------------------------------------- 1 | 2 | {{- $reveal_location := $.Param "reveal_hugo.reveal_cdn" | default "reveal-js" -}} 3 | {{- $highlight_location := $.Param "reveal_hugo.highlight_cdn" | default "highlight-js" -}} 4 | {{- $custom_theme := $.Param "reveal_hugo.custom_theme" -}} 5 | 6 | 7 | {{- $custom_theme := $.Param "reveal_hugo.custom_theme" -}} 8 | {{- if $custom_theme -}} 9 | {{- $custom_theme_options := $.Param "reveal_hugo.custom_theme_options" | default dict -}} 10 | {{- if $.Param "reveal_hugo.custom_theme_compile" -}} 11 | {{ $asset := resources.Get $custom_theme | resources.ExecuteAsTemplate "_.scss" . | toCSS $custom_theme_options | minify | fingerprint }} 12 | 13 | {{- else -}} 14 | 15 | {{- end -}} 16 | {{ else -}} 17 | {{- $theme := $.Param "reveal_hugo.theme" | default "black" -}} 18 | 19 | {{ end -}} 20 | {{ if $.Param "reveal_hugo.load_default_plugins" | default true -}} 21 | 22 | {{- $highlight_theme := $.Param "reveal_hugo.highlight_theme" | default "default" -}} 23 | 24 | {{- end }} 25 | {{- $custom_css := $.Param "reveal_hugo.custom_css" -}} 26 | {{- if $custom_css -}} 27 | 28 | {{- end -}} 29 | 30 | {{ partial "highlight-style.html" . }} 31 | {{ with $.Params.countdown }} {{ end }} -------------------------------------------------------------------------------- /content/distill/demo/index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Notes from the demo 3 | menuTitle: Demo 4 | weight: 5 5 | slides: true 6 | output: hugodown::md_document 7 | rmd_hash: 56c6444412ac02ba 8 | 9 | --- 10 | 11 | - show the RStudio IDE, ask whether anyone is unfamiliar with it. 12 | 13 | - install the distill package, [`install.packages("distill")`](https://rdrr.io/r/utils/install.packages.html) 14 | 15 | - create blog (from RStudio Create New Project, not [`distill::create_blog()`](https://rdrr.io/pkg/distill/man/create_website.html)). 16 | 17 | - what's in the folder now? 18 | 19 | - show website in local browser. 20 | 21 | - [`usethis::use_git()`](https://usethis.r-lib.org/reference/use_git.html) 22 | 23 | - change site but not URL, and about. change citations: true!!! 24 | 25 | - rebuild the site via RStudio build button or [`rmarkdown::render_site()`](https://rdrr.io/pkg/rmarkdown/man/render_site.html). 26 | 27 | - show website in local browser. 28 | 29 | - edit and knit welcome. including author info!! 30 | 31 | - look what changed, commit 32 | 33 | - show website in local browser. 34 | 35 | - look at post html in \_posts and \_site. mention navbar 36 | 37 | - commit 38 | 39 | - add a post with [`distill::create_post()`](https://rdrr.io/pkg/distill/man/create_post.html). knit, look what changed this time. 40 | 41 | - add references 42 | 43 | - add latex, mention JavaScript 44 | 45 | - add footnote and aside 46 | 47 | - put website online via Netlify drag and drop. 48 | 49 | - add base\_url to site config, show citations metadata is added. 50 | 51 | - Netlify drag and drop. 52 | 53 | - Some minimal styling. Introduce the web developer console. 54 | 55 | - Netlify drag and drop 56 | 57 | - GitHub repo [`usethis::use_github()`](https://usethis.r-lib.org/reference/use_github.html) 58 | 59 | - mention git checkout -b and [the distill docs about blog post workflows](https://rstudio.github.io/distill/blog_workflow.html). 60 | 61 | - Other options for deployment (Netlify link to repo, [distill docs](https://rstudio.github.io/distill/publish_website.html)) 62 | 63 | - add Twitter&GitHub 64 | 65 | -------------------------------------------------------------------------------- /content/reproducibility/slides/index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | outputs: 3 | - Reveal 4 | title: Workflows 5 | hidden: true 6 | layout: list 7 | weight: 1 8 | output: hugodown::md_document 9 | rmd_hash: d72ca81ec9ad4774 10 | 11 | --- 12 | 13 | Reproducibility? 14 | ================ 15 | 16 | Should your blog posts still be "knittable?" 17 | 18 | ------------------------------------------------------------------------ 19 | 20 | Reproducibility? 21 | ================ 22 | 23 | - Be able to update your post short/medium term 24 | 25 | - Same for readers except for private data 26 | 27 | {{% fragment %}}
But blog posts will **age**, which is fine, a blog is not a current docs website. {{% /fragment %}} 28 | 29 | ------------------------------------------------------------------------ 30 | 31 | All posts 32 | ========= 33 | 34 | Need to re-knit posts for migration, tool updates? 35 | 36 | {{% fragment %}} Or use the R Markdown output after a point (.md), potentially with YAML/other tweaks. 37 | 38 | When I migrated from Jekyll to Hugo I used the .md, not .Rmd. {{% /fragment %}} 39 | 40 | ------------------------------------------------------------------------ 41 | 42 | Evergreen posts 43 | =============== 44 | 45 | If you want a tutorial to be evergreen you'll need to ensure it works with the latest packages etc. 46 | 47 | But are tutorials like package vignettes? 48 | 49 | ------------------------------------------------------------------------ 50 | 51 | Reproducible analyses 52 | ===================== 53 | 54 | How to archive your computing environment? 55 | 56 | It might be "easier" to archive the analysis elsewhere (tools for scientific articles) and link to that from the blog post. 57 | 58 | ------------------------------------------------------------------------ 59 | 60 | Transparency 61 | ============ 62 | 63 | For you, for readers. 64 | 65 | - Add session info to bottom of posts 66 | 67 | - Mention data origin (URL to data?) 68 | 69 | ------------------------------------------------------------------------ 70 | 71 | Common sense 72 | ============ 73 | 74 | - Backup 75 | 76 | - Make note of anything that might be tricky (dev version of a package) 77 | 78 | ------------------------------------------------------------------------ 79 | 80 | What's your own take? 81 | ===================== 82 | 83 | -------------------------------------------------------------------------------- /content/promotion/slides/index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | outputs: 3 | - Reveal 4 | title: Readers 5 | hidden: true 6 | layout: list 7 | weight: 1 8 | output: hugodown::md_document 9 | --- 10 | 11 | # Promote your blog 12 | 13 | --- 14 | 15 | # Put its URL everywhere! 16 | 17 | Your ORCID profile, Twitter profile, GitHub profile, etc. 18 | 19 | No dead ends please! 20 | 21 | --- 22 | 23 | # R Weekly 24 | 25 | Weekly newsletter featuring links to blog posts but also slidedecks, etc., about R. 26 | 27 | * One-off sharing: [web form](https://rweekly.org/submit), [PRs](https://github.com/rweekly/rweekly.org). 28 | 29 | * Add your RSS feed via the [web form](https://rweekly.org/submit). 30 | 31 | --- 32 | 33 | # R Bloggers 34 | 35 | Ingests the entire feed and repost posts. 36 | 37 | It can take time from [feed submission](https://www.r-bloggers.com/add-your-blog/) to feed validation. 38 | 39 | --- 40 | 41 | # Social media 42 | 43 | E.g. Twitter. 44 | 45 | Write a clear text, post URL, add a few hashtags, image (or carefully crafted infographics?) + alternative text. 46 | 47 | --- 48 | 49 | # SEO 50 | 51 | Search Engine Optimization 52 | 53 | * Add links to your post 54 | 55 | * Read resources by marketers 56 | 57 | --- 58 | 59 | # Interact with readers 60 | 61 | --- 62 | 63 | # How to interact with readers? 64 | 65 | On social media? 66 | 67 | In comments? For Hugo, [Utteranc.es as an alternative to Disqus](https://masalmon.eu/2019/10/02/disqus/). 68 | 69 | --- 70 | 71 | # Negative feedback 72 | 73 | (not constructive feedback) 74 | 75 | Have a support system. 76 | 77 | You don't have to respond publicly, or at all. 78 | 79 | If _you_ were wrong, listen and do better. 80 | 81 | --- 82 | 83 | # Encouraging citations 84 | 85 | --- 86 | 87 | # Citing your posts 88 | 89 | * Distill metadata 90 | 91 | * Hugo [custom layout](https://github.com/statnmap/hugo-statnmap-theme/blob/3e2a54a9836fdd65779865e91058ba304b628336/layouts/partials/citation.html) 92 | 93 | * [DOI](https://twitter.com/mfenner/status/1126523120591020032)? 94 | 95 | --- 96 | 97 | # Analytics 98 | 99 | --- 100 | 101 | # Analytics 102 | 103 | * Do you need numbers? E.g. if you blog at work. 104 | 105 | * Are you ok using Google Analytics? 106 | 107 | * GDPR :wink: 108 | 109 | * Alternatives? [Fathom](https://usefathom.com/)? Others? -------------------------------------------------------------------------------- /content/hugo/demo/index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: Notes from the demo 3 | menuTitle: Demo 4 | weight: 5 5 | slides: true 6 | output: hugodown::md_document 7 | --- 8 | 9 | - install the remotes package, `install.packages("remotes)` 10 | 11 | - install the hugodown package, `remotes::install_github("r-lib/hugodown")` 12 | 13 | - `hugodown::hugo_install()` 14 | 15 | - new RStudio empty project. 16 | 17 | - `hugo new site . --force` from the command line in that new folder. 18 | 19 | - Download https://github.com/yihui/hugo-xmin and put into themes, remove "-master" from the folder name, delete example site. 20 | 21 | - Copy paste https://github.com/yihui/hugo-xmin/blob/master/exampleSite/config.toml 22 | 23 | - Create `_hugodown.yaml` with `hugo_version: 0.73.0` 24 | 25 | - `hugodown::hugo_start()` 26 | 27 | - add about.md 28 | 29 | - copy-paste from [hugodown setup vignette](https://hugodown.r-lib.org/articles/config.html) 30 | 31 | - create [static/css/code.css](/snippets/#codecss) from and create [layouts/partial/head_custom.html](/snippets/#head_customhtml) (one should read [theme docs](https://xmin.yihui.org/about/)!) 32 | 33 | - for mathjax create [layouts/partial/foot_custom.html](/snippets/#head_customhtml) 34 | 35 | - create post in content/post/2020-06-25-cool/index.Rmd and copy-paste from snippets page. knit, preview. 36 | 37 | - add citations. 38 | 39 | - `hugodown::hugo_stop()`, `hugodown::hugo_start(render_to_disk = TRUE)` 40 | 41 | - Netlify drag and drop 42 | 43 | - add URL to config 44 | 45 | - then something easier from the code point of view but more overwhelming! 46 | 47 | - create empty RStudio project (with git if it's available) 48 | 49 | - `hugodown::hugo_install('0.66.0')` 50 | 51 | - `hugodown::create_site_academic()`. Be happy to see everything happening automatically :sparkles: 52 | 53 | - `hugodown::hugo_start(render_to_disk = TRUE)`, open localhost in the browser. 54 | 55 | - Change site title and [theme](https://sourcethemes.com/academic/themes/) in config/_default/params.toml. Yes a theme for a theme! 56 | 57 | - Mention [academic docs](https://sourcethemes.com/academic/), all the things one can change. 58 | 59 | - `hugodown::use_post("post/new-rmd-post")`, knit, see post. 60 | 61 | - say there will probably be other themes later. show [Hugo theme gallery](https://themes.gohugo.io/) and how I would choose themes. 62 | 63 | - `usethis::use_github()`, `hugodown::use_netlify_toml()`, go to Netlify interface. 64 | 65 | - add URL to config 66 | -------------------------------------------------------------------------------- /content/conclusion/slides/index.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | outputs: 3 | - Reveal 4 | title: Conclusion 5 | hidden: true 6 | layout: list 7 | weight: 1 8 | output: hugodown::md_document 9 | rmd_hash: b777bbe39c9e64c8 10 | 11 | --- 12 | 13 | Scientific blogging with R Markdown 14 | =================================== 15 | 16 | :sob: Nearly time to say goodbye! 17 | 18 | ------------------------------------------------------------------------ 19 | 20 | - distill: perfect, not flexible 21 | 22 | - Hugo&hugodown: very flexible (too flexible?), changes fast, experimental R package 23 | 24 | - WordPress&goodpress: also flexible, even more experimental R package 25 | 26 | ------------------------------------------------------------------------ 27 | 28 | What to choose 29 | ============== 30 | 31 | - distill 32 | 33 | - Hugo Academic with [`hugodown::create_site_academic()`](https://rdrr.io/pkg/hugodown/man/create_site_academic.html) 34 | 35 | - WordPress if you already use WordPress? 36 | 37 | ------------------------------------------------------------------------ 38 | 39 | What to choose 40 | ============== 41 | 42 | Start by playing! Don't commit right away. 43 | 44 | Does any of you want to say what they'd choose and why? 45 | 46 | ------------------------------------------------------------------------ 47 | 48 | True for all 49 | ============ 50 | 51 | - Read the docs and follow development! :eyes: 52 | 53 | - Backup! :warning: 54 | 55 | ------------------------------------------------------------------------ 56 | 57 | Change your mind? 58 | ================= 59 | 60 | - Migration tools 61 | 62 | - `yaml`, `commonmark` packages, etc. 63 | 64 | - Redirects! URLs are important. 404 page. 65 | 66 | ------------------------------------------------------------------------ 67 | 68 | Have fun! 69 | ========= 70 | 71 | If you're worried about blogging, find a blogging buddy to read your drafts? 72 | 73 | Make efforts but don't be perfectionist. 74 | 75 | ------------------------------------------------------------------------ 76 | 77 | Setup is not fun 78 | ================ 79 | 80 | - With R helper packages, setup is smoother 81 | 82 | - But in general setup = learning a new thing, hard but then you get used to it! 83 | 84 | ------------------------------------------------------------------------ 85 | 86 | Regular blogging? 87 | ================= 88 | 89 | No you don't have to unless you call your blog "the daily blog" or so. :wink: 90 | 91 | Only write if you enjoy it! Your blog can be a portfolio/news board only. 92 | 93 | ------------------------------------------------------------------------ 94 | 95 | Tell me 96 | ======= 97 | 98 | - Questions this afternoon :raising_hand: 99 | 100 | - Issues in the [website repo](https://github.com/maelle/rmd-blogging-course/issues) for questions :raising_hand: 101 | 102 | - [Tweets](https://twitter.com/ma_salmon)/emails to show me your websites. :star: 103 | 104 | -------------------------------------------------------------------------------- /content/distill/slides/index.en.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | outputs: 3 | - Reveal 4 | title: distill 5 | hidden: true 6 | layout: list 7 | weight: 1 8 | output: hugodown::md_document 9 | countdown: true 10 | --- 11 | 12 | # Distill 13 | 14 | --- 15 | 16 | [Distill](rstudio.github.io/distill/) is both a framework and an R package. 17 | 18 | > Distill for R Markdown is a web publishing format optimized for scientific and technical communication. 19 | 20 | --- 21 | 22 | * Output format for single documents 23 | 24 | * Websites 25 | 26 | * Blogs, like websites but with blog posts than aren't re-rendered automatically. 27 | 28 | --- 29 | 30 | Helpers like `distill::create_post()` 31 | 32 | --- 33 | 34 | # From Rmd to website 35 | 36 | Under the hood 37 | 38 | 39 | ```{=html} 40 | {{}} 41 | graph LR; 42 | A[Rmd] -->|"R ( distill :package:) & Pandoc & Distill framework" | B[HTML] 43 | {{< /mermaid >}} 44 | ``` 45 | 46 | Inspired by [Emi Tanaka's post](https://emitanaka.org/r/posts/2018-12-12-scientific-and-technical-blogging-radix-vs-blogdown/) 47 | 48 | --- 49 | 50 | # From Rmd to website 51 | 52 | What you do 53 | 54 | 55 | ```{=html} 56 | {{}} 57 | graph LR; 58 | A[Rmd] -->|" :large_blue_circle: knit button" | B[HTML] 59 | {{< /mermaid >}} 60 | ``` 61 | 62 | 63 | --- 64 | 65 | :train: Time for a demo! 66 | 67 | [Notes on the course website](/distill/demo/) 68 | 69 | --- 70 | 71 | Scientific Rmd Blog Checklist 72 | 73 | * [x] R Markdown 74 | * [x] Syntax highlighting (for all knitr-supported languages) 75 | * [x] Modern 76 | * [x] .bib 77 | * [x] Citation for posts 78 | * [x] Equations 79 | 80 | --- 81 | 82 | # Sustainability 83 | 84 | Created by: 85 | 86 | ```{r, echo=FALSE, results="asis"} 87 | glue::glue_collapse( 88 | trimws( 89 | gsub("<.*>", "", 90 | desc::desc_get_author(file = find.package("distill"), role = "aut") 91 | ) 92 | ), 93 | sep = ", ") 94 | ``` 95 | 96 | Used for [RStudio AI blog](https://blogs.rstudio.com/ai/), in particular. 97 | 98 | Active development. 99 | 100 | --- 101 | 102 | # Limitations? 103 | 104 | * Content stored as html (harder to migrate?) 105 | 106 | * Limited possibilities for customization (blessing in disguise?) 107 | 108 | * Some open issues (ORCID support, RSS feed tweaking) but active development 109 | 110 | --- 111 | 112 | # Further resources 113 | 114 | [Listed on the course website](/distill/further-resources/) :books: 115 | 116 | --- 117 | 118 | # Questions, comments? 119 | 120 | Write them in the pad! 121 | 122 | --- 123 | 124 | # Time for a break :coffee: 125 | 126 | 127 | 128 |

129 | 130 | 05:00 131 | 132 |

133 | 134 | -------------------------------------------------------------------------------- /content/distill/further-resources.en.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: More about distill 3 | menuTitle: Further resources 4 | weight: 50 5 | --- 6 | 7 | ## Read the manual :wink: 8 | 9 | There aren't many pages in [distill docs website](https://rstudio.github.io/distill/) so I'd recommend reading all of them if you commit to this website builder. 10 | 11 | ## Follow developments? :eyes: 12 | 13 | If you start using distill for your website... 14 | 15 | * Read the changelog when updating the package? 16 | 17 | * [Watch development on GitHub](https://help.github.com/en/github/managing-subscriptions-and-notifications-on-github/viewing-your-subscriptions#configuring-your-watch-settings-for-an-individual-repository)? 18 | 19 | * Subscribe to the [issues](https://github.com/rstudio/distill/issues) that are interesting to you: [search](https://github.com/rstudio/distill/issues/9), [ORCID](https://github.com/rstudio/distill/issues/21), etc.? 20 | 21 | ## Websites for inspiration :sparkles: 22 | 23 | | Website | Source | 24 | |---|---| 25 | |[Scholarly Communication Analytics](https://subugoe.github.io/scholcomm_analytics/)| [