index.md (4939B)
1 --- 2 title: Using RStudio and RMarkdown with Hugo 3 description: One approach to blogging with RMarkdown and Hugo. 4 date: 2022-07-10T17:03:47-04:00 5 draft: False 6 categories: 7 - Meta 8 - Programming 9 - Data Science 10 tags: 11 - R 12 - Hugo 13 --- 14 15 I converted my site to [Hugo](https://gohugo.io/) recently, and I finally 16 figured out a workflow to create blog posts using RMarkdown from inside 17 RStudio. None of the instructions that I found online worked the way I 18 wanted (for instance, [hugodown](https://hugodown.r-lib.org/) requires a 19 specific out-of-date version of Hugo), so I'm sharing my workflow in case 20 it's useful for anybody else. 21 22 ## Things to do once 23 24 There are a few basic setup steps that should only need to be performed 25 once. 26 27 ### Setup Hugo 28 29 Hugo setup is beyond the scope of this post. I mostly followed [this 30 quickstart guide](https://gohugo.io/getting-started/quick-start/). 31 32 ### Set a `HUGO_ROOT` environment variable 33 34 Create a new environment variable `HUGO_ROOT` and set it to the directory in 35 which you created your site. In my case, I'm using: 36 37 ```bash 38 HUGO_ROOT="~/web/www.eamoncaddigan.net/" 39 ``` 40 41 There are (too) many ways to set an environment variable. I edited 42 `~/.profile`, but `~/.bashrc` will work for many folks. Using `~/.Renviron` 43 would also be appropriate if you're not planning to use this variable for 44 anything outside of R and RStudio. 45 46 ### Create a location for RMarkdown files outside of Hugo 47 48 You could keep your `.rmd` files in your Hugo site, and it might even be 49 possible to have Hugo knit them for you. But since I'm currently on my third 50 static site generator, I wanted to use a separate git repository for blog 51 posts, outside of the rest of my site configuration. 52 53 ## Things to do for every post 54 55 Here are the steps to take every time you create a new blog post. 56 57 ### Launch the Hugo server 58 59 Running Hugo's built-in server lets you preview your post as you work on it. 60 Run the following command in the shell: 61 62 ```bash 63 hugo server -DF 64 ``` 65 66 When you initially run this in a terminal, it will print a URI at which you 67 can point your web browser, e.g., `http://localhost:1313/`. Go ahead and 68 open that in your browser. 69 70 ### Create a new RMarkdown file in RStudio 71 72 When you create a new RMarkdown file in RStudio, you can fill in a title for 73 your post in the GUI, or you can do it later. It doesn't matter which output 74 format you select since we're going to change that in the next step. 75 76 ### Edit the RMarkdown YAML 77 78 Here's the YAML block for my last post: 79 80 ```md 81 --- 82 title: "Labeling bar charts (and other graphics) in ggplot2" 83 description: "How to combine stats and geoms to simplify complex plots." 84 date: 2022-07-08T19:32:57-04:00 85 draft: False 86 knit: (function(input, ...) { 87 rmarkdown::render( 88 input, 89 output_dir = file.path(Sys.getenv("HUGO_ROOT"), "content/posts") 90 ) 91 }) 92 output: 93 md_document: 94 variant: markdown 95 preserve_yaml: true 96 --- 97 ``` 98 99 Change the title, description, and date as appropriate for your post, and 100 set `draft` to `True` for now. 101 102 The function used with `knit` is invoked when you press the "Knit" button in 103 RStudio. It specifies that the rendered content (a markdown file) is put in 104 `$HUGO_ROOT/content/posts`. 105 106 The options passed to `output` tell `knitr` to generate Markdown output by 107 default. Preserving YAML is important because Hugo uses that to organize 108 posts, and the `markdown` variant has good code highlighting, etc. 109 110 You might want to set `tags`, I ought to start doing that soon. 111 112 ### Set chunk and knit options 113 114 Set `knitr` chunk and knit options in the first code chunk of the file: 115 116 ```r 117 knitr::opts_chunk$set( 118 echo = TRUE, 119 fig.path = file.path("figs", 120 sub("\\.Rmd$", "", 121 basename(rstudioapi::getActiveDocumentContext()$path)), 122 "") 123 ) 124 knitr::opts_knit$set( 125 base.dir = file.path(Sys.getenv("HUGO_ROOT"), "static"), 126 base.url = "/" 127 ) 128 ``` 129 130 These options ensure that figures are put in the correct local directory, 131 and that the links will work online. This specific configuration places 132 figures in `http://example.com/figs/rmarkdown-filename/chunk-name-N.png`, 133 and you can tweak this as you see fit. You can pass additional named 134 arguments to `knitr::opts_chunk$set()` that you like, such as `fig.width`. 135 136 ### Write a good post 137 138 If it's *really* good, please let me know about it! 139 140 Clicking the Knit button in RStudio will create a new markdown file inside 141 your local Hugo site. The Hugo server will see the changes and generate a 142 new site, and your browser should refresh the site to display the changes 143 (Hugo injects special JavaScript to do this when you're previewing with its 144 server). 145 146 ### Finish up 147 148 When you finish your post, set `draft` to `False` in the YAML, kill the Hugo 149 server, and run `hugo` (with no additional options) to generate your static 150 site. Upload that site to your host and feel good about freely sharing your 151 knowledge with the broader community.