Updating website

Author

Galen Holt

Website

Finding new pages

I often work on a bunch of pages and actually merge and push rarely. To identify pages that are present in the repo but not yet in the yaml (and so will not be included in the website), I wrote a little function that finds the files not in the yaml and also qmds in the yml but without a file, as when we change filenames. It’s available in the functions dir and here:

find_missing_pages <- function() {
  qmd_in_proj <- list.files(pattern = "*.qmd", recursive = TRUE)
  qmd_in_yml <- readLines("_quarto.yml") |> 
    purrr::keep(\(x) grepl(".qmd", x)) |> 
    gsub('\\s', '', x = _) |> 
    gsub('-', '', x = _) |> 
    gsub('href:', '', x = _)
  # The values in the `render` section are still there, but that's ok
  
  not_present <- which(!(qmd_in_proj %in% qmd_in_yml))
  
  missing_pages <- qmd_in_proj[not_present]
  
  no_file <- which(!(qmd_in_yml %in% qmd_in_proj))
  
  broken_links <- qmd_in_yml[no_file]

  
  return(list(missing_pages = missing_pages, no_file_present = broken_links))
}

Page linking

I keep getting dead links, because I think I don’t understand how links of the form

[words](path/to/quarto_doc.qmd)

work. Do I need the path? Should the path be relative to the root, or the particular document being rendered?

To test, this doc is in the /website_notes folder, as is quarto_website_github.qmd, while another set of small helpers is in /small_helpers/smallpieces.qmd. I’m going to try to link to both of those in a couple different ways and see what works. Actual text is in code chunks so it’s visible.

no outer dir, same folder quarto_website_github.qmd : WORKS

[quarto_website_github.qmd](quarto_website_github.qmd)

no outer dir, different folder smallpieces.qmd : FAILS

[smallpieces.qmd](smallpieces.qmd)

outer dir, same folder quarto_website_github.qmd : FAILS

[quarto_website_github.qmd](website_notes/quarto_website_github.qmd)

outer dir, different folder smallpieces.qmd : FAILS

[smallpieces.qmd](small_helpers/smallpieces.qmd)

referenced to file dir, different folder smallpieces.qmd : (doesn’t make sense to do this for the same folder, since the implication is that the reference is to the directory with the qmd in it). WORKS

[smallpieces.qmd](../small_helpers/smallpieces.qmd)

So, LINKS NEED TO BE RELATIVE TO THE LOCATION OF THE FILE. That’s really annoying, and I thought would have been controlled by setting execute-dir: project in the yaml, but that doesn’t seem to be the case.

Is there a good way to find and fix dead links? Need to look.

Github pages not updating

Very frequently pushes to main will still not seem to work- the website will remain in the old state, despite being sure we’ve pushed to main and the local render and preview has all the new content. The issue seems to be caching, and I’m not sure why it’s so aggressive. In chrome, you can open the Inspector, then right-click on the refresh button and then “empty cache and hard reload”. Or incognito window, or clear the cache some other way. It’s very annoying though.

Re-rendering

I had thought that pushing the ‘Render’ button in Rstudio built the whole site- it throws errors for other qmds than the one I currently build. BUT, if that’s all I do and then push and publish, pages that I haven’t specifically rendered are outdated- e.g. the sidebar and content don’t show updates. So it seems that we have to actually quarto render at the terminal first? I think- I’m trying to do that and all the R-python pages have broken.

Ah. I see now that there’s a warning about this in the quarto docs:

As you preview your site, pages will be rendered and updated. However, if you make changes to global options (e.g. _quarto.yml or included files) you need to fully re-render your site to have all of the changes reflected. Consequently, you should always fully quarto render your site before deploying it, even if you have already previewed changes to some pages with the preview server.

Weirdness

If there is a folder called ‘website’ in the repo, quarto will throw an error on render ‘unsupported project type ../website’. The solution seems to be to change the folder name.

Errors

I get a lot of errors rendering this site. Often the solution is to trash the _cache and _filesdirectories for the offending files, along with any generated .html or .md . What seems to work the best though, is to delete everything in .Rproj.user. And often restart Rstudio.

Some common errors are

Error: path for html_dependency not found: C:/Users/username/AppData/Local/Temp/Rtmp...

An error about permissions being denied (os error 5) trying to move site_libs: ERROR: PermissionDenied: Access is denied. (os error 5), rename 'path/to/repo/site_libs' -> 'path/to/repo/docs/site_libs'

Part of the issue seems to be Dropbox, even if the code is only in a backup directory and not a fully-synced directory. It sometimes works to quit dropbox, but sometimes we need to do that and restart.