Website Upgrading Logs

Introduction

This documents the changes made to the academic theme to make this website work when upgrading from Hugo ver=0.47 and Academic Theme ver=2.4.

The upgrade for this website was performed on 12-19-2018.

All in all, it took the better part of an entire day to get familiar with all the nooks and crannies of the new updates and plan out the migration of the more complicated website… Mathematical Michael.

Changes Made to Theme

  • Removed Weibo sharing icon in /layouts/partials/share in the theme directory.
  • Changed footer in layouts/partials/footer_section.html
  • Re-did config.toml line-by-line, disabled night/day mode.

  • Created slides and docs based on the exampleSite folder, including creating the directory /assets/css/reveal_custom.css for the Reveal.js slideshows.

    • added boards.jpg to /static/img/ to test headers and embeds in the example slideshow.
    • created slides.md in /content/ to link to /content/slides/ folder since using an index file does not work to list the available slideshows in that folder.

  • created /wid/ and /dockerhub/ to experiment with new docs template.

  • copied over dummy project files, still need to migrate own projects to new formatting, remove dummy projects.

  • Changed work hyperlink and resume to reflect new migration to the docs template.

  • resume widget changed to hyperlink to resume doc.

To-Do

  • header/feature images for post, check how fb/twitter scrapes them.
    • optional feature image without becoming header will be useful for posts that are galleries.
  • migrate any posts/projects to new formatting.
  • think about how to migrate MathematicalMichael.

Next Steps

Things I’m Considering

  • No need to re-make publication type.
    • Since posts can be linked to projects, and filters can be applied within widgets, we should have all the flexibility we need.
    • Taken with the new folder structure of pages, the overall directory structure remains quite clean.

  • Use widgets pagetype to construct/mimick the /artwork page.

    • Have carousels and project widgets linking to galleries and slideshows.

  • Can additionally link out to a docs page that describes the art in more depth, also linked to from the projects page of Probably Art to tell the “story” of this project over time and in its phases.

    • Phase 1: Directed Study
    • Phase 2: Pickup with Pocket CHIP, restart coding in Python
    • Phase 3: After some time, picked it up again and added a whole bunch of functionality, attempted to get random art automated in Squarespace
    • Phase 4: Pick up again when I get into GCode. Adds functionality.
    • Phase 5: Lapse again. Then finally tackle creating a framework that will work long-term. Talk about requirements. How is has to be in Python, based on stable packages, recreatable and deterministic. GCode scalable. Talk about some to-do’s (bumpers, bash scripts that wrap around to position plotter better). Show images of getting plotter back up again.
    • Phase 6: Merge with Animation code/projects. Talk about goals, current progress. Random animations on non-random images
    • Have another to tell the story of Moving Pictures

Upgrading to Hugo v0.52

Date: 12/21/18

Today I began to structure and fill in the basic information for the Open Science Documentation. It involved some research and collection of resources from disparated places and things I’ve done before.

I also sat down and in a couple minutes managed to figure out the “breaking changes” to my MathematicalMichael website under Hugo v0.52. The only file that needed to be changed (before updating the theme, that is) was the $i, reference in a file I made myself:

vim themes/academic/layouts/partials/artwork_links.html

Next step was to copy the theme from michaelpilosov/ (which pulled from the github repo only a few days prior, and to which some minor changes were made) into mathematicalmichael/themes/ along with a copy of the config file.

Motivation

Once the reference to the new theme is made, I expect a number of things to break.

Here I will attempt to document one-by-one the changes I had to make to port my theme over, which I will attempt to do by leveraging the “lookup structure” of Hugo (something I read online).

The idea is that rather than make changes to a theme that result in deviations that make merging new changes difficult, one makes changes by copying files into directories that are checked first, before themes/ is searched for layouts or partials files. My hope is that this will aid in future upgrades, since less differences will exist between my version of the theme and the master branch. A really useful command (for comparing files), that I used to see what needed to change in the master configuration file for my theme (compared to the updated one from this website) was:

diff -y file1.md file2.md

which will print out two files side-by-side directly into the UNIX Terminal. Excellent.

Academic Theme v0.3.32

After making the appropriate changes to the config.toml file (which were all straightforward), I ensured that the site built with the new Hugo and the new configuration file but without the new theme. It did. All was well.

Then I changed the theme to point to the updated one:

theme = "hugo-academic"

which yielded the following error (kind of expected to be honest):

Error: 
Error building site: 
failed to render pages: 
render of "home" failed: 
execute of template failed: 
template: index.html:4:3: 
executing "index.html" at <partial widget_page...>: 
error calling partial: 
"/media/mathematicalmichael/HANK/repos/mathematicalmichael/themes/hugo-academic/layouts/partials/widget_page.html:23:9": 
execute of template failed: 
template: partials/widget_page.html:23:9: 
executing "partials/widget_page.html" at <partial $widget $par...>: 
error calling partial: 
Partial "widgets/artworks.html" not found

So why did this happen?

Well, I had defined my own template page called artworks that was modeled on the publications style of page. I used this to publish a webpage for each piece of art, complete with a rich tagging-system automated through Python. I made random art and had written code that created pages for that art to live on. Any changes made to the front-matter could be easily applied later.

I believe that simply moving some files to directories that exist above themes will resolve my problems.

Image Galleries

However, I know there will be an opportunity to switch to page-bundles and leverage the image-gallery feature in v3.0 of Hugo-Academic. My thinking is as follows:

  • Instead of daily pages, make weekly ones as galleries.
  • Alternatively, keep daily postings as-is, and add galleries additionally. See if you can link images to the main folder, so all art can continue to live in one folder without duplicates.
  • You can make galleries using page-bundles as a separate way to interact with the art.

  • Definitely need to integrate a widget page that hosts all the art. I don’t want to clutter the home page with everything.

    • I think that clicking from the main menu to art/ should suffice.
    • Curate the experience, minimize contact with /artwork/ page (i.e. make slideshows link to other content rather than the search they perform now, which can be a bit slow.

  • Since slideshows are just a markdown file, we should have no trouble linking to images in another folder!

    • will take some playing around to figure out exactly the right directory structure.

** Main Goal ** for the time being is to make sure the site builds with the new theme. We can add features and functionality later on.

Today’s agenda is simply to allow migration to Hugo v0.52 on my Macbook by ensuring the site builds with the new version. Having the new theme work would be an added bonus.

I suspect all that needs to happen is a little migration of partials and shortcodes.

cp themes/academic/layouts/partials/artwork_* layouts/partials/

Did not change the error.

mkdir layouts/partials/widgets/
cp themes/academic/layouts/partials/widgets/artworks* layouts/partials/widgets/

Resolved that but sprang a new error:

Error: 
Error building site: 
failed to render pages: 
render of "home" failed: 
execute of template failed: 
template: 
index.html:4:3: 
executing "index.html" at <partial widget_page...>: 
error calling partial: 
"/media/mathematicalmichael/HANK/repos/mathematicalmichael/themes/hugo-academic/layouts/partials/widget_page.html:23:9": 
execute of template failed: 
template: 
partials/widget_page.html:23:9: 
executing "partials/widget_page.html" at <partial $widget $par...>: 
error calling partial: 
Partial "widgets/search.html" not found

Okay, so let’s move widgets/search.html over?

cp themes/academic/layouts/partials/widgets/search.html layouts/partials/widgets/

hugo server --disableFastRender

And that did it! Wow, relatively painless. Now let’s see how it looks.

The layout is dark for some reason… Enabling light/dark mode shows me the white I want to see but with inverted header. :mailto icon is broken. Change to “fas” instead of “fab” in config.toml, line 293.

Back to the theme.. let’s grab a file and move it to the root directory and figure out where to put it.

cp themes/hugo-academic/data/themes/dark.toml .
mkdir data
mkdir data/themes
mv dark.toml data/themes/

I then proceeded to change some things to get the right colors. Still not sure if this is correct. I also changed the theme to self.toml and referenced that in the config.toml file.

Dark Mode

Next test: Day/Night mode (re-enable, see what happens).

Day Mode is fine. Night mode makes my logos look weird (though I do like the look overall). Top bar is also white instead of black for some reason.

Editing data/themes/self.toml to rename the theme (mistake to not have done that before), and toggle light = true, since I did make it into a light theme.

# Theme metadata
name = "Self"

# Is theme light or dark?
light = true

# Primary
primary = "hsl(339, 90%, 68%)"
primary_light = "hsl(339, 90%, 78%)"
primary_dark = "hsl(339, 90%, 58%)"

# Menu
menu_primary = "#fff"
menu_text = "rgba(0,0,0,0.6)"
menu_text_active = "hsl(339, 90%, 68%)"
menu_title = "#2b2b2b"

# Home sections
home_section_odd = "rgb(255, 255, 255)"
home_section_even = "rgb(247, 247, 247)"

Note: Also broken is the search widget. Sad.

Disable search widget… Should not have moved it in the first place! There is a new search feature that renders this one useless. I will now remove the search.html widget (and search.md from content/home/

Contact form… Had to paste in the new format. I was using a custom partial code (note to self… delete that) to make a formspree link. Now I don’t have to!

Also, remove Search from menu in config.toml. After deleting layouts/shortcodes/contactme.html (my custom formspree link), in favor of using the one the upgraded theme provided, it appears that my website is now settled into the new theme. I did have to remove all references to this deleted shortcode, of course.

Day/night mode works correctly. (would like to make my logo transparent though).

Page Bundles

Okay, well I knew it was too good to be true that things just worked. While pages loaded correctly, before building the final site, I made sure to investigate the directories a bit more and found that a bunch of files prepended with ._XXX.md had populated my website directories. This must be how they’re ensuring backward-compatibility.

Well, I refactored the pages into page bundles with this shell script:

#!/bin/sh

# Helps migrate from v2.4.0 to v3.0.0
#
# Refactor a page named `X.md` to `content/<section>/X/index.md` to use the
# new page bundles and featured image system
#
# - E.g. a post `content/post/X.md` is converted to `content/post/X/index.md`

refactor_pages_to_page_bundles()
{
  if [ ! -d ./content/ ]; then
    echo "Please run script from root of hugo site"
  fi
  local files="$(find ./content/ -iname '*.md' -not -iname '*index.md' -not -ipath './content/home/*')"
  for file in ${files}; do
    local pagedir="${file%.md}"

    echo "${file} -> ${pagedir}/index.md"
    if [ ! -d "${pagedir}" ]; then
      mkdir "${pagedir}"
    fi

    mv "${file}" "${pagedir}/index.md"
  done
}

# Bash Strict Mode
set -eu

# set -x
refactor_pages_to_page_bundles "$@"

Source

After poking around, it looks like the pages obey the proper structure now (for the most part)… There are a few stray .md files around.

I will push the changes live but later on go through both websites to ensure that bundles are everywhere and no stray pages are left.

Search/Filter

Notably, I will need to

  • update my python script that writes project pages and art pages.
  • ensure featured images (optional) are properly handled
  • find out how galleries can work with the artwork/images directory, which so far doesn’t seem to be conflicting with the page-bundle format.
  • Make sure the artwork search works. Seems to be broken, though publications search still works.

Oh, I think all that needs to happen is to move /themes/academic/layouts/artwork into the layouts folder I have in my root directory.

mv themes/academic/layouts/artwork/ layouts/

But that led to an error regarding partial header_image.html. Thus, it seems like I will need to copy the new publication template over and edit it again. At least this time I will document it.

cp themes/hugo-academic/layouts/publication/single.html  layouts/artwork/

And then I replaced all instances of publication with artwork

But that still didn’t lead to the filter-ability that I wanted.

The default behavior was to paginate and list all of the art, which doesn’t have image previews but honestly is just fine, especially since it loads quickly.

The widget on the homepage that links to the search of artwork though is now broken as a consequence. I can fall back on searching by tags, or disable the widget temporarily until I set up galleries for the artworks.

  • If I write a python script that scrapes the artwork/images folder and creates galleries linked to that, well that would be just perfect.
  • This widget can be linked to those galleries, or slideshows.
  • Disable it for now.

Okay, later at night I had to come across this as well, but I wanted the listing of artworks in their projects, so I copied the new layouts/partials/project/single.html into the layouts/partials/projects/ directory I created and pasted the following relevant chunk of code:

<br>
      <h4> Archive </h4>
      {{ $items := where (where .Site.RegularPages "Type" "artwork") ".Params.projects" "intersect" (slice $project) }}
      {{ $items := $items | union (where (where .Site.RegularPages "Type" "artwork") ".Params.url_project" $project_path) }}
      {{ $arts_len := len $items }}
      {{ if ge $arts_len 1 }}
        <h4>{{ (i18n "artworks") }}</h4>
        {{ range $items }}
          {{ if eq $page.Site.Params.projects.artwork_format 1 }}
            {{ partial "artwork_li_detailed" . }}
          {{ else }}
            {{ partial "artwork_li_simple" . }}
          {{ end }}
        {{ end }}
      {{ end }}

And I got my desired lists!

See here for example.

Table of Contents

I also realized I needed to edit the table of contents with some custom CSS.

Create a custom file in /static/css and link it to line custom_css = [] in config.toml:

#TableOfContents{
    padding-left: 10px
}
dev webdev
Last updated on Jan 1, 2019