Building this website

Han Oostdijk

2019/01/14

Date last run: 01Nov2019

This website

I am starting to build a website with the blogdown package in the Hugo environment with the hugo-xmin theme. Most of the content until now consists of material included for illustration and documentation purposes by Yihui Xie.

All credits to Yihui Xie and friends. The old about page by Yihui is still included in this website here.

Had problems while deploying to a subfolder of old website

Hugo Forums provided as solution to include the following statements in config.toml:

baseurl = "www.hanoostdijk.nl/hugo/"
...
RelativeURLs=true
CanonifyURLs=true
...

But see RSS feed was not considered valid and config.toml used for the full configuration file.

Case sensitivity

After deploying a png file was not shown while it displayed correctly while testing with blogdown:::serve_site() ?
It appeared that the extension had not the correct case. Apparently the test environment is more forgiving.

RSS feed was not considered valid

My email reader Thunderbird refused to accept the RSS feed produced by the website because it was not correctly validated. In a StackOverflow article Yihui Xie advises to specify a full baseurl. In my case that should be http://www.hanoostdijk.nl/hugo/. And this indeed solved the problem. See config.toml used for the full configuration file.

Syntax coloring not working yet

I expected that syntax coloring for code would work out-of-the-box but it did not. In the original About page Yihui Xie points to pull request 5 of hugo-xmin for instructions. The file foot_custom.html in the partials folder has to be edited. But also with these instructions it did not work.
Amber Thomas advises to include the highlight and MathJax statements in config.toml (see config.toml used) but no relief.
Then I realized that I also should include in head_custom.html a css reference custom footer as indicated in pull request 5 . After I copied the reference from the html in the example webpage to head_custom.html the syntax highlighting worked as expected.

I wanted to include a fixed link to a page with news about an area in China: Xiongan New Area. I create this page from time to time dynamically from a Google Alert source (see here).
I started with placing the page in the contents/post section but each time I would change the date I would also have to change the link (because of the permalink specification in config.toml).
My second solution was placing the page in the static section without a date, but I saw that the md-file was not converted to html (indeed: static section).
My final (for the time being) solution was to create a new section contents/xiong-an without a permalink specification as for notes and posts. That implies that the date is not used for this page but only the slug ‘xiong-an-news’. I now can use the reference ‘[here](/xiong-an/xiong-an-news/)’ that is independent of the date to create the link here .

Problem with including an image (with a specific name??)

While preparing a post about handling financial data I wanted to include an image of the input sheet. The image was named liquidity.PNG . I expected this to work with the code <img src="/liquidity.PNG" alt="liquidity sheet" width="80%"/> because the PNG file was placed in the static folder. However no image was shown. After some ‘googling’ I found that there is a blogdown add-in to insert images. The add-in produced an invalid target path (not found out why yet) but after correcting this I saw that it generated as name Iiquidity.PNG in folder \static\post\2019-03-18-checking-future-balances-with-expected-transactions_files. I copied liquidity.PNG (NB not Iiquidity.PNG) to this folder and the image was shown.

So the strange thing (for me at least) is that the code (and the resulting html) contains a reference to Iiquidity.PNG that is not in the folder and the image in liquidity.PNG (that is in the folder) is shown. When I renamed the file to Aiquidity.PNG everything worked as expected: I could use <img src="/Aiquidity.PNG" alt="liquidity sheet" width="80%"/> . However because I do not like the idea to have the static folder mass populated with individual files, I think I will use the idea to use a static\post subfolder for each post such as the one mentioned above.

So it looks like that the software handles filenames (or strings?) starting with 'li' or '/li' differently ??

Update 12AUG2019: after blogdown version 0.14.1 the add-in works fine. I have not checked if the Iiquidity.PNG section above now works as expected.

Created a local_files folder

While working on post I again had some problems with the location of the input file jpg file. So this is much related to the previous entry.

This is a static file so it could be placed in ..\content\post but to keep it organised I would like to place it in a folder related to this document. Such a folder exists: “../../static/post/2019-06-29-image-and-enlargement-of-a-section_files”

However when I copy to this folder it can not be found: the list.files function indicates that the “2019-06-29-image-and-enlargement-of-a-section_files” is not a subfolder of ../../static/post

No clue, why that is the case. I also tried to use the addin “Insert Image” but this fails: it generates a non-valid folder name and does not create a folder ??

Solutions: I created a subfolder of ../../static/post with the name I wanted to use but added ‘_a’ just to make it different. This works.

Later on I realized that there is no need for the input and output file to be on the website. Therefore I created a folder local_files under the root folder that will not be included in the website. In this I created the subfolder without the ‘_a’ suffix.

Additional css statements

The library css/mycss.css was added to the static subfolder and made known to Hugo by adding it in the head_custom.html file. Currently it contains information for .mycap that is generated by the function center_cap, for table.HOQC (used for tables that should not look like tables) and slightly adapted information for the accentuation of code.

Archetypes

In the file D:\data\R\my_website_xmin\archetypes\standard.md I have inserted a statement that produces a last-run line. See here. Update 27AUG2019: in default.md the same statement is inserted.

Inserted code for Table of Contents

When the metadata of an entry contains showtoc=T the first levels of the Table of Contents are printed. The default value for the number of levels is 3 (i.e. H2 and H3 headers will be included in the Table of Contents). The numbers of levels can be overwritten by a toclevel entry in the YAML header e.g. 'toclevel: 5' when the headers up to level 5 (H2, H3, H4 and H5) are shown.
To get this working the single.html file in D:\data\R\my_website_xmin\layouts\_default has been adapted. See single.html.

Update some files before rerendering the website

In the Configuration note I display the version of RStudio that I currently use. In the rendering stage this version can not be retrieved because the blogdown environment does not use RStudio. Therefore I use the contents of the file rstudio_version.RDS. The function update_HOQC updates this file and also 'touches' files. The latter will force the rerendering of notes/posts that are not changed but include files that maybe changed.

R statements used

The RStudio blogdown addins Serve Site and New Post were used as were the following R statements

library(blogdown)
blogdown::new_site(install_hugo = F,format='yaml',sample=T,  
   theme='yihui/hugo-xmin',hostname='www.github.com',
   theme_example = T,to_yaml=T)
   
serv_handler = blogdown:::serve_site()
servr::daemon_stop(serv_handler)   
servr::daemon_stop(servr::daemon_list()) # or servr::daemon_stop() 

blogdown::build_site(local = FALSE, method = "custom")
# or since August 2019 
#   (see post 13AUG2019 Custom rendering of Hugo posts and notes)
blogdown::build_site() 

blogdown::update_hugo()
blogdown:: install_theme('yihui/hugo-xmin',
  theme_example = TRUE,force=TRUE,update_hugo = F)

blogdown::hugo_cmd('version')
blogdown::hugo_cmd('help')
blogdown::hugo_cmd('config')

config.toml used

The current contents of the configuration file is

baseurl = "https://www.hanoostdijk.nl/hugo/"
languageCode = "en-us"
title = "HanOostdijk Datascience"
theme = "hugo-xmin"
googleAnalytics = ""
disqusShortname = ""
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
preserveTaxonomyNames = true
footnotereturnlinkcontents = "↩"
RelativeURLs=true
CanonifyURLs=true

[permalinks]
    post = "/post/:year/:month/:day/:slug/"
    note = "/note/:year/:month/:day/:slug/"

[[menu.main]]
    name = "Home"
    url = "/"
    weight = 1
[[menu.main]]
    name = "About"
    url = "/about/"
    weight = 2
[[menu.main]]
    name = "Notes"
    url = "/note/"
    weight = 3
[[menu.main]]
    name = "Posts"
    url = "/post/"
    weight = 4
[[menu.main]]
    name = "Categories"
    url = "/categories/"
    weight = 5
[[menu.main]]
    name = "Tags"
    url = "/tags/"
    weight = 6
[[menu.main]]
    name = "Links"
    url = "/links/"
    weight = 7
[[menu.main]]
    name = "Subscribe"
    url = "/index.xml"

[params]
    description = "A Hugo website (template hugo-xmin) built with R package blogdown."
    footer = "&copy; [Han Oostdijk](https://www.hanoostdijk.nl/hugo/about/) 2019 | [Github](https://github.com/HanOostdijk) | [Twitter](https://twitter.com/HanOostdijk)"

    highlightjsVersion = "9.11.0"
    highlightjsCDN = "//cdn.bootcss.com"
    highlightjsLang = ["r", "yaml"]
    highlightjsTheme = "github"

    MathJaxCDN = "//cdn.bootcss.com"
    MathJaxVersion = "2.7.1"

foot_custom.html used

The current contents of foot_custom.html in the partials folder is

<script src="//yihui.name/js/math-code.js"></script>
<script async src="//mathjax.rstudio.com/latest/MathJax.js?config=TeX-MML-AM_CHTML"></script>

<script async src="//yihui.name/js/center-img.js"></script>

<script src="//cdn.bootcss.com/highlight.js/9.12.0/highlight.min.js"></script>
<script src="//cdn.bootcss.com/highlight.js/9.12.0/languages/r.min.js"></script>

<script>
hljs.configure({languages: []});
hljs.initHighlightingOnLoad();
</script>

head_custom.html used

The current contents of head_custom.html in the partials folder is

<link rel="stylesheet" href="{{ "/css/mycss.css" | relURL }}" />
<link href="//cdn.bootcss.com/highlight.js/9.12.0/styles/github.min.css" rel="stylesheet">

adapted css statements

The current contents of mycss.css in the static\css folder is :

.mycap {
  font-size: 0.9em;
  font-style: italic;
  color: grey;
}

table.hoqc {
  margin-left: 0;
  border: none;
}

table.hoqc tbody{
  line-height: 1.0em;
}
table.hoqc tr{
  background: none;
}
table.hoqc td{
  padding-left: 0;
}
code { 
  background: #e9e9e9; 
  font-family: 'PT Mono', monospace;
  font-size: 0.8em;
  white-space: pre;
}

adapted single.html file

To include a Table of Contents I had to change the single.html. I copied the version to a newly created folder D:\data\R\my_website_xmin\layouts\_default and included the code to create a Table of Contents. Acknowledgements are included in the file:

{{ partial "header.html" . }}
<div class="article-meta">
<h1><span class="title">{{ .Title | markdownify }}</span></h1>
{{ with .Params.author }}<h2 class="author">{{ . }}</h2>{{ end }}
{{ if (gt .Params.date 0) }}<h2 class="date">{{ .Date.Format "2006/01/02" }}</h2>{{ end }}
</div>

<main>

{{/* adapted from https://github.com/alex-shpak/hugo-book/issues/52 kchen0x */}}
{{/* used https://gist.github.com/pyrrho/1d77cdb98ba58c7547f2cdb3fb325c62   */}}
{{/* https://github.com/gohugoio/hugo/issues/1778 */}}

{{/* ignore empty links with + */}}
{{- $toclevel := default (default 3 .Site.Params.toclevel) .Params.toclevel }}
{{ if lt $toclevel 6}}
{{ $.Scratch.Set "toclevel" $toclevel }}
{{ else }}
{{ $.Scratch.Set "toclevel" 3 }}
{{ end }}
{{- $toclvl := $.Scratch.Get "toclevel" -}}
{{- $regstring := printf "<h[2-%d].*?>(.|\n])+?</h[2-%d]>" $toclvl $toclvl -}}
{{- $headers := findRE $regstring .Content -}}
{{ .Scratch.Set "last_level" 1 }}

{{/* at least one header to link to */}}
{{- $has_headers := ge (len $headers) 1 -}}
{{- if $has_headers -}}

{{ $showToC := default (default false .Site.Params.showToC) .Params.showToC }}
  {{ if and ($showToC) (.Page.TableOfContents) }}
    <nav id="TableOfContents">
      <summary>
      <b>Table of Contents</b>
      </summary>
      {{- range $headers -}}
          {{- $last_level := $.Scratch.Get "last_level" -}}
          {{- $header := . -}}
          {{- $base := ($.Page.File.LogicalName) -}}
          {{- $anchorId := index (findRE "id=.([a-z0-9-_])*" $header) 0 | after 4 -}}          
          {{- $a14 := substr $anchorId 0 14 }}
          {{- if ne $a14 "date-last-run-" -}}          
              {{- $href := delimit (slice $base $anchorId) "#" | string -}}
              {{- range findRE "[2-5]" . 1 -}}
                  {{- $next_level := (int .) -}}
                  {{- if gt $next_level $last_level -}}
                      {{- range seq (add $last_level 1) $next_level}}
                          <ul class="toc-h{{ . }}">
                      {{- end -}}
                  {{- else if lt $next_level $last_level -}}
                      {{- range seq (add $next_level 1) $last_level}}
                          </ul>
                      {{- end -}}
                  {{- end -}}
                  <li><a href="{{ relref $.Page $href }}"> 
                     {{- $header | plainify | htmlUnescape -}}
                  </a></li>
                  {{ $.Scratch.Set "last_level" $next_level }}
              {{- end -}}
          {{- end -}}
      {{- end -}}
      </nav>
{{ end }}
{{- end -}}

{{ .Content }}
</main>

{{ partial "footer.html" . }}

standard.md in archetypes

The current contents of standard.md in the archetypes folder is

---
title: ''
date: ''
---

##### Date last run: `r format(Sys.time(), '%d%b%Y')`

update_HOQC function

This function is used to update the file rstudio_version.RDS and to 'touch' files with includes, so that they are forced to be rendered again :

update_HOQC <- function(...) {
  # save RStudio version for reporting in rmarkdown
  v1 <- as.character(rstudioapi::versionInfo()$version)
  saveRDS(v1, './local_files/rstudio_version.RDS')
  # touch notes with 'includes'
  notes_pref <- './content/note/'
  notes <-
    c(
      '2019-01-14-building-this-website.Rmarkdown',
      '2019-08-13-custom-rendering.Rmarkdown',
      '2019-08-26-configuration.Rmd'
    )
  purrr::walk(paste0(notes_pref, notes),
              fs::file_touch)

  # touch posts with 'includes' (currently none)
  posts_pref <- './content/post/'
  posts <-
    c()
  purrr::walk(paste0(posts_pref, posts),
              fs::file_touch)
}