Hello Hugo Apéro: Converting a Blogdown Site from Hugo Academic | Silvia Canelón

[utterances-bot]

Hello Hugo Apéro: Converting a Blogdown Site from Hugo Academic | Silvia Canelón

A tutorial on how to take your personal Hugo Academic/Wowchemy website and convert it to the Hugo Apéro theme

https://silvia.rbind.io/blog/2021-hello-hugo-apero/

[liutiming]

Thanks!

[kwanlin]

Thanks Silvia for this excellent writeup! I was wondering if you had any suggestions on how to implement to "On This Page" table of contents that you have in the sidebar? From what I can tell, this is implemented using some additions and tweaks to the /layouts directory?

[spcanelon]

Hi @kwanlin! Thanks for your question -- it will be the first one I answer using Utterances! 🔮
You are correct about the table of contents, it's implemented as an HTML partial in the /layouts folder. I'll outline some steps below:

Step 1. Create a custom partial for the table of contents (i.e. post-toc.html) like I do here:

silvia/layouts/partials/shared/post-toc.html

Lines 1 to 12 in 831e2cf

	{{ $page := . }} <!--save current page-->
	{{ $page_toc_label := .Params.sidebar.text_contents_label | default "On this page" }}
	<!--check for headers-->
	{{ $headers := findRE "<h[2].*>" $page.Content }}
	{{- $has_headers := ge (len $headers) 1 -}}
	{{- if $has_headers -}}
	<!--insert ToC-->
	<nav id="TableOfContents" class="sticky ph4 pb4 pt6" role="navigation">
	<h2 class="mv0 f5 fw7 ttu tracked dib">{{ $page_toc_label }}</h2>
	{{ .TableOfContents }}
	</nav>
	{{ end }}

Step 2. Copy the single-sidebar.html file from the themes/hugo-apero layouts folder into your own layouts folder. In my case:

• From: themes/hugo-apero/layouts/blog/single-sidebar.html
• To: layouts/blog/single-sidebar.html

Step 3. Insert the table of contents partial from Step 1 into the single-sidebar.html layout using:

{{ partial "shared/post-toc.html" . }}

Seen in context below:

silvia/layouts/blog/single-sidebar.html

Lines 28 to 34 in 831e2cf

	<aside class="page-sidebar" role="complementary">
	{{ partial "shared/sidebar-scaffold.html" . }}
	<!--{{ .Scratch.Set "details" "open" }}-->
	{{ .Scratch.Set "details" "closed" }}
	{{ partial "shared/post-details.html" . }}
	{{ partial "shared/post-toc.html" . }}
	</aside>

Step 4. Tweak the table of content settings in the config.toml file to suit your preferences:

silvia/config.toml

Lines 23 to 26 in 831e2cf

	[markup.tableOfContents]
	startLevel = 1
	endLevel = 2
	ordered = false

---

For another very similar implementation you can explore Alison Hill's single-sidebar.html and sidebar-toc.html setup.

There are some extra things going on with my site that make it so the table of contents styling changes as the reader scrolls down the page. The implementation is a little clunky at the moment (I don't know JavaScript!) but I linked to some resources in #23 (comment) to go along with the commits if you're interested 🔍

[kwanlin]

Thank you for the detailed response! It looks like the two things that were tripping me up were:

1. I didn't adjust my config.yaml file (not too sure why it's not a .toml, I'm guessing I checked some option when I was getting things set up with blogdown)
2. I had some already-rendered content in my contents/blog section prior to the addition of the table of contents, which seems to have gotten in the way of the table of contents rendering properly when I subsequently made the changes.

[Tai-Rocha]

Thanks for this post !!
Unfortunately, I receive the error aforementioned (
Error: Error building site: failed to render pages: render of "page" failed: execute of template failed: template: _default/single.html:3:8: executing "_default/single.html" at <partial "head.html" .>: error calling partial: execute of template failed: template: _internal/schema.html:24:82: executing "_internal/schema.html" at <.Params.tags>: range can't iterate over Data Science).

But everything was ok until I decided to update blogdown to 1.6 version and Hugo to 0.89.4 version and now I can not update the site. Any idea about how to fix it?

Thanks in advance !!

[spcanelon]

Hi @Tai-Rocha! Thanks for reading the post. Blogdown and Hugo issues can be tricky to figure out! Here are some questions to consider:

1. Did you update the Hugo version in all the places? Described in https://silvia.rbind.io/blog/hello-hugo-apero/#hugo-version
2. Did you see this error (I'm guessing in step 5) even after going through the rest of the steps in the post? My version of this error eventually went away.

[yabellini]

Excelent post! I'm following to migrate my web site. When I move my blog content I found that some of my post don't show on the list (actually the blog only show one). I have to remove the type parameter on the YAML to all the post. Sharing this here jus in case some one else found this issue.

[nvelden]

When transferring my old posts I noticed that .Rmd files are directly rendered to .html files thus any Apero specific theme settings are not included. Converting the files to .Rmarkdown fixed the issue. Also sharing in case somebody else runs into the same problem.

[yabellini]

I did the deploy with different steps:

1. I changed the default branch in github to the apero branch (using the options in Setting on the web)
2. I changed the default branch in my local repo to apero with this command:
   git remote set-head origin -a
3. I changed the name of the deploy branch in netlify to apero.

That avoid the merge conflicts and has to delete the files one more time.
My new website: https://yabellini.netlify.app
My old website was left in the master branch: https://master--yabellini.netlify.app/ (I probably should change the name :-) )

Gracias por este tutorial, me ayudó muchisimo!