Getting started with blogdown on Synology

Prerequisites

• RStudio.
• blogdown and dependencies: Yihui Xie et al.’s Creating Websites with R Markdown (the “blogdown book”) is well worth reading in its entirety, but this post assumes you have read at least the Installation section (and followed the instructions therein).
• A Synology NAS¹.

Initial setup

We will broadly follow setup suggested in the blogdown book getting started section.

First, though, we set up/initialise a remote git repository. If you don’t have the Synology git package installed already, install it from Package Center, then ssh into the server with admin privileges and execute a git init (repalcing /volume1/git/michaelbolgernet.git with your desired repository path/name; the --bare option is required for a remote repository):

git init --bare /volume1/git/michaelbolgernet.git

Alternatively, any other git host will do (or none, though then disregard other git-relevant instructions below).

Clone the empty repository onto your local machine in RStudio via File > New Project > Version Control > Git, then enter the repository URL etc:

Or clone the repository directly in the Terminal:

git clone ssh://[email protected]:2222/volume1/git/michaelbolgernet.git michaelbolger.net

In either case, the URL format is the same:

protocol://username@[domain or IP address][:port if non-standard]/path/to/repository.git /path/to/localrepository

Next, run File > New Project again, but this time selecting the New Directory > Website using blogdown option to create the basic site framework:

Generally, a new RStudio project should be created in an empty directory. For these purposes, however, the project directory we have just created by cloning the bare remote repository is sufficiently empty.

• The ‘Install Hugo automatically’ option does nothing if Hugo is already installed, and so can be left enabled.
• ‘Add sample blog posts’ adds a sample R Markdown post from the blogdown package, which may be useful in helping understand the capabilities of R Markdown, but can be ignored if you are already familiar with this.
• ‘Add the example site of the theme’ copies the example site for the theme into the main site directory. While optional–these files are anyway available within the themes/<theme name>/exampleSite directory–it is nevertheless helpful, especially when first setting up/exploring a site.

Regarding selecting a theme, don’t get side-tracked by shiny things–you will waste a lot of time before you end up back with the blogdown default theme (Lithium) or another one of the blogdown-recommended themes (see the getting started section of the blogdown book)². See Themes, below, for further discussion on selecting a Hugo theme.

config.toml

The config.toml file in the site’s root directory is the main configuration file. Edit this file as required³. My config.toml ended up like this (material deviations from the default Lithium config.toml are commented):

baseurl = "http://michaelbolger.net/"
languageCode = "en-us"
title = "michaelbolger.net"
theme = "hugo-lithium"
author = "Michael Bolger"
# googleAnalytics = ""
# disqusShortname = "michaelbolger"
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]

# Amend default Lithium permalink behaviour.
[permalinks]
   post = "/post/:year-:month-:day-:slug/"

[[menu.main]]
    name = "Home"
    url = "/"
    weight = 1
[[menu.main]]
    name = "About"
    url = "/about/"
[[menu.main]]
    name = "Projects"
    url  = "/projects/"
# [[menu.main]]
#     name = "GitHub"
#     url = "https://github.com/rstudio/blogdown"
[[menu.main]]
    name = "Twitter"
    url = "https://twitter.com/michaelbolger"

[params]
    description = "Tech and other musings, primarily relating to Apple, Synology, and R."

    # options for highlight.js (version, additional languages, and theme)
    highlightjsVersion = "9.12.0"
    highlightjsCDN = "//cdnjs.cloudflare.com/ajax/libs"
    highlightjsLang = ["r", "yaml", "ini", "bash"]
    highlightjsTheme = "github"

    # MathJaxCDN = "//cdnjs.cloudflare.com/ajax/libs"
    # MathJaxVersion = "2.7.5"

    # path to the favicon, under "static"
    favicon = "favicon.ico"

    [params.logo]
    url = "logo.png"
    width = 50
    height = 50
    alt = "Logo"

I changed the permalink behaviour as I feel, for a low-volume site, having nested directories for each month/year is too crufty. See the configuration section of the blogdown book for further details on these settings.

Content

Create source documents for any pages you specified in config.toml–there is an About page in the Lithium example site, but you’ll need to edit its content, and the Projects page does not exist. From the RStudio Addins toolbar button, select New Post then amend as appropirate:

Note, to create a top-level page, ensure ‘Subdirectory’ is blank.

Create a new post in the same way:

When you create a post in this way, the date you include for the post is included as part of the filename of the file (and in the YAML metadate). You can amend the suggested filename when creating a post, but I like to keep the date in there so that sorting the files by name in a directory listing also sorts them by date.

You can use a date in the future for a post that is a work-in-progress. Similarly, you can add draft: true to the post’s YAML metadata. In each case, such posts are rendered locally (e.g. when using the Serve Site add-in), but are not rendered when building the site for deployment⁵.

You can use the Update Metadata add-in to, well, update a post’s metadata:

As noted in the blogdown book, this is primarily useful for updating categories and tags as it prompts you with those you have already used in other posts. Changing the date or slug (or title, if it is used to define your permalinks), or selecting the ‘Rename file if the date is changed’ option, should be done with caution, as these actions will likely break any existing links to the post. In general, if a post is new and there are no other references to it in your blog, it’s safe to change these metatdata at will (though see caveat in Images and static files, below), but it is best avoided post publication.

Code chunks

The great power of R Markdown comes when using code chunks. Code chunks can be used to run any supported code (R, bash, as well as Python/SQL/etc. if supported on your system). Typically, in the context of a blogdown site, code will be used to create output to be included in the post, e.g. a chart–the code is run when the site is built, and the output is copied as part of the generated static files to the public directory. Another use for code chunks is to display code with syntax highlighting, which is great for readability, particularly for longer sections of code.

However, by default, code included in a code chunk is run as-is, and there is no restriction on what it can do. This is potentially Very Important, depending on what code you include in your code chunks. Say you want to display the bash command echo Hi > ~/hi.txt, nicely formatted in a code block with proper bash syntax highlighting:

echo Hi > ~/hi.txt

You might include the following code chunk in your source R Markdown file:

```{bash}
echo Hi > hi.txt
```

If you did this with default settings, you would be leaving a message to yourself in your root user directory, every time you built your site:

Imagine the mess you could get yourself into if you were writing a post on dangerous terminal commands, say⁷.

```{bash eval=FALSE}
echo Hi > hi.txt
```

```{r include=FALSE}
knitr::opts_chunk$set(eval=FALSE, warning=FALSE, message=FALSE)
```

```{toml}
baseurl = "http://michaelbolger.net/"
...
```

Site preview

To preview your site, use the Serve Site add-in–this will start an internal web server and serve your site locally on your computer. The console output will tell you the IP address and port to view your site, e.g. 127.0.0.1:4321.

Committing

This completes the basic setup but before we commit our changes, we should ignore unnecessary files to keep the remote repository clean. Amend the root .gitignore file as follows:

# RStudio defaults
.Rproj.user
.Rhistory
.RData
.Ruserdata

# macOS
.DS_Store

# blogdown generated files
content/**/*.html
public/

We can ignore the public directory because its contents are generated automatically. As noted, .Rmd files clutter up the contents directory with corresponding .html files, so these can be ignored too. The /**/ syntax ignores matching files in the contents directory and any sub-directories.

Commit changes using RStudio’s git functionality, or directly at the Terminal:

git add -A
git commit -m "Initial commit of blogdown site."
git push origin master

Hosting setup

To host a website on a Synology, it must be running a web server–this is managed using the Web Station package. On your Synology, install the Web Station package from the Package Center. The default Web Station settings are fine to leave as is.

Routing

Update 2020-11-18:

Synology keeps losing its router-assigned static IP address. Current MAC address: 00:11:32:5B:BB:0E. Set static IP address via the Synology instead.

Synology-declared MAC address: 00-11-32-5B-BB-0D Mac address per router: 00:11:32:5B:BB:0E (for ‘wifi-bridge-2’, the switch?)

Your site is now on your Synology, but nobody outside of your network can see it because your domain does not yet point to it. To fix this:

• Your Synology must be accessible from the internet. This means that the appropriate ports must be forwarded from your router to your Synology, and you need to have a way of keeping track of your public IP address (unless you have a fixed IP address, which is generally not the case for most home broadband services).
• The DNS settings for your domain name must ultimately resolve to your Synology.

Updating

To update, follow the steps set out in Deploying your site, above, bearing in mind that any changes you deploy are now available for all the world to see¹². To recap:

• Session > Restart R in RStudio.
• Delete the local copy of your site’s public directory.
• Run build_site() to build the site for deployment.
• Copy all of the contents of your site’s public directory to the web directory of your site (select ‘Overwrite’).

If you have made any changes that change filenames/paths or delete files (e.g. removing an inserted image), make sure you manually delete the corresponding files in your web directory, otherwise they will still be available, even if they are not linked from anywhere else on your site. A belt-and-braces approach is delete the entire contents of your web directory and re-upload the whole site.

This overwrite/delete and re-upload deployment workflow is ineffiient, and may become cumbersome as your site grows larger–it won’t all be available for the period between the delete and the completion of the upload, for example–but should be manageable for sites with a modest number of pages/posts. We will look at more efficient deployment methods in a later post.

One gotcha to look out for is, if you are making edits to a post that has already been published, when you re-upload your site and navigate to the post in your browser, you may still see the old version that was cached by your browser. If you reload, it should load the new version (unless you are being served a cached-version from elsewhere, in which case you might just have to wait until that cache is refreshed).

Themes

This is down here because I think your first priority should be getting a working site up and running, rather than agonising over selecting and tweaking a theme.

When selecting a theme, consider what you want, and in what order. I wanted:

• blogdown/R Markdown/RStudio compatability
• Responsive design
• Top navigation elements (i.e., no side-bar)
• Syntax highlighting
• Disqus support
• Sparse design aesthetic
• Custom fonts

Then, focus on finding a theme that matches the functionality you want, rather than one you find aesthetically pleasing. I initially settled on themes that matched the design aesthetic I was looking for, for example Introduction, but this proved far too complex for me to get it to play well with blogdown. I then tried Black & Light which is a much simpler theme, but even then I spent fruitless hours trying to get it to work seamlessly with blogdown. So finally I came back to the default Lithium theme, which supports all of the core functionality I want, and I will work on tweaking its aesthetics to make it more to my liking.

Next steps

• Add TLS encryption with Let’s Encrypt.
• Enable Disqus commenting on posts (but not static pages).
• Use git functionaltiy to maintain link to upstream theme code, while allowing for tweaks specific to this site.
• Use custom fonts.
• Tweak Lithium theme to make the look and feel more to my liking.