Customizations of Hugo-Academic

As you can see, this website is built using the Academic Theme for the Hugo static site generator. Nonetheless I spent some time doing some additional customization, some of which are described below.

arXiv listing

Instead of using the "Publications" feature of the Academic theme, I instead rely on generating my list of research articles using using a modified version of the arXiv.org Javascript widget. The modification is mainly for formatting the output. Instead of the default definition list (<dl>...</dl>) format used in the original version published by arXiv, I formatted the output mirroring the card layout for the accomplishments widget of the Academic theme.

To load the arXiv widget, which I store as static/js/arxiv_widget.js, I add to layouts/partials/head_custom.html the following code to load local Javascript files

{{- range .Params.addLocalJs }}
<script type = "text/javascript" src="/js/{{ . }}.js"></script>
{{- end }}

which can be activated by including the parameter

addLocalJs = [ "arxiv_widget" ]

at the top of the relevant markdown content file.

MathJax

I use the following configuration for MathJax (going into assets/js/mathjax-config.js)

window.MathJax = {
	CommonHTML: { linebreaks: { automatic: true }, minScaleAdjust: 100 },
	tex2jax: { 
		inlineMath: [ ['$', '$'], ['\\(','\\)'] ], 
		displayMath: [ ['$$','$$'], ['\\[', '\\]'] ], 
		processEscapes: true, 
		processEnvironments: true},
  	TeX: { 
		noUndefined: { attributes: { mathcolor: 'red', mathbackground: '#FFEEEE', mathsize: '100%' } },
		equationNumbers: {autoNumber: "AMS"},
		},
  messageStyle: 'none'
};

Font and color

The main font for this site is the Vollkorn font available on Google Font.

The color scheme is given by

# Theme metadata
name = "MSU"

# Is theme light or dark?
light = true

# Primary
primary = "#48756b"
primary_light = "#38655b"
primary_dark = "#08352b"

# Menu
menu_primary = "#18453b"
menu_text = "#fff"
menu_text_active = "#0DB14B"
menu_title = "#fff"

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

Tag listing

For the tags page, I like a tag cloud better than a straight-up list. So layouts/tag/terms.html becomes (copied from the tag cloud code for Academic)

{{ partial "header.html" . }}
{{ partial "navbar.html" . }}

{{ partial "page_header.html" . }}

<div class="universal-wrapper">
  {{ with .Content }}
  <div class="article-style" itemprop="articleBody" style="font-style: italic;">{{ . }}</div>
  {{ end }}

{{ if not (eq (len $.Site.Taxonomies.tags) 0) }}
      {{ $fontSmall := 0.8 }}
      {{ $fontBig := 2.5 }}

      {{ $fontDelta := sub $fontBig $fontSmall }}
      {{ $min := len (index $.Site.Taxonomies.tags.ByCount.Reverse 0).Pages }}
      {{ $max := add (len (index $.Site.Taxonomies.tags.ByCount 0).Pages) 1 }}
      {{ $delta := sub $max $min }}
      {{ $fontStep := div $fontDelta $delta }}

      <div class="tag-cloud">
        {{ range $name, $taxonomy := $.Site.Taxonomies.tags }}
          {{ $tagCount := len $taxonomy.Pages }}
          {{ $weight := div (sub (math.Log $tagCount) (math.Log $min)) (sub (math.Log $max) (math.Log $min)) }}
          {{ $fontSize := add $fontSmall (mul (sub $fontBig $fontSmall) $weight) }}
          <a href="{{ ($.Site.GetPage (printf "tags/%s" $name)).RelPermalink }}" style="font-size:{{ $fontSize }}rem">{{ $name }}</a>
        {{ end }}
      </div>
    {{ end }}
  

</div>
{{ partial "footer_container.html" . }}
{{ partial "footer.html" . }}

Similarly, the tag listings layouts/tag/list.html are borrowed also:

{{ partial "header.html" . }}
{{ partial "navbar.html" . }}

{{ partial "page_header.html" . }}

<div class="universal-wrapper">
  {{ with .Content }}
  <div class="article-style" itemprop="articleBody" style="font-style: italic;">{{ . }}</div>
  {{ end }}

  {{ $paginator := .Paginate .Data.Pages }}
  {{ range $paginator.Pages }}
  {{ partial "li_compact" . }}
  {{ end }}

  {{ partial "pagination" . }}
</div>
{{ partial "footer_container.html" . }}
{{ partial "footer.html" . }}

Dates for posts

I like to see both the original post dates and the last edited dates for my posts. The last edited dates are automatically generated using Git, and is shown by default by the Academic theme if you configure it to do so. The original post dates are however suppressed in this scenario. To amend that, I edited layouts/partials/page_metadata.html so that the part that generates the article date reads instead (depending on the version of Academic you are using, the code below may need some simple changes).

<span class="article-date">
    {{ $date := $.Lastmod.Format $.Site.Params.date_format }}
    {{ if eq $.Type "publication" }}
      <time>{{ $.Date.Format ($.Site.Params.publications.date_format | default "January, 2006") }}</time>
    {{ else if eq $.Type "post" }}
      <time>{{ $.Date.Format $.Site.Params.date_format }}</time>
      {{ if ne $.Params.Lastmod $.Params.Date }}
      <span class="middot-divider"></span>
        {{ i18n "last_updated" }}
	<time>{{ $date }}</time>
      {{ end }}
    {{ else }}
      {{ if ne $.Params.Lastmod $.Params.Date }}
          {{ i18n "last_updated" }}
      {{ end }}
      <time>{{ $date }}</time>
    {{ end }}
</span>

Theorem and proofs

Since I will be writing mathematics, I want to have something that approximates the Theorem and Proof environments of LaTeX. In particular I want to be able to have the tombstone symbol to indicate the end of the proof environment.

These can be done using short codes.

Proofs

layouts/shortcodes/proof.html reads:

<div class="proof">
	<div class="proofheader">Proof{{ with .Get "title" }} [{{.}}]{{ end }}:</div>
	<div class="proofbodycontainer">
	<div class="proofbody">{{ .Inner | markdownify }}</div>
	<div class="prooftomb"></div>
	</div>
</div>

It can be used with or without an optional title parameter in the short code.

{{< proof >}}
Insert your proof here
{{< /proof >}}

or

{{< proof title="Of Theorem 1" >}}
Insert your proof here
{{< /proof >}}

With the former the heading reads "Proof:" in italics; with the latter it reads "Proof [of Theorem 1]:".

The laying out of the content, including the insertion of the tombstone symbol, are all done in CSS. assets/css/theoremproof.css (remember to load this as a css plugin in the site config) reads:

.prooftomb:after {
	content: "\220E";
}

.prooftomb {
	width: 0.8rem;
	font-size: 120%;
	font-weight: 900;

}

.proofbody {
	flex: 1;
}

.proofbody p:last-child,
.thmbody p:last-child {
	margin-bottom: 0rem;
}

.proofbodycontainer {
	display: flex;
	align-items: flex-end;
	border-left: 0.1rem solid lightgrey;
	margin-left: 0.2rem;
	padding-left: 0.5rem;
}

.proof {
	margin-top: 0.5rem;
	margin-bottom: 0.5rem;
}

.thmlike {
	margin-top: 0.5rem;
	margin-bottom: 0.5rem;
	counter-increment: theorem;
}

.proofheader {
	font-style: italic;
	border-bottom: 0.1rem solid lightgrey;
}

.thmheader {
	font-weight: bold;
	border-bottom: 0.1rem solid lightgrey;
}

.thmtype {
	font-variant: small-caps;
}

.thmtype:after {
	content: counter(theorem)
	;
}

.thmbody {
	border-left: 0.1rem solid lightgrey;
	margin-left: 0.2rem;
	padding-left: 0.5rem;
}

A note on implementation: there are many CSS code floating around on the internet setting proof environments with tombstones. The "obvious" solution that most people use is to set

.proof:after {
	float: right;
	content: "\8718";
}

which when used with the HTML code

<div class="proof">
  Type your proof.
</div>

will place the tombstone on the final line of the proof, and floated to the right. This however can be an issue if the final bit of your proof consists of something displayed as a block, or as a closed paragraph.

<div class="proof">
   <p>First paragraph of proof</p>
   <p>Secton paragraph of proof</p>
</div>

In this second example, the float will be set after the end of the second paragraph, and will then float into any text that follows the end of your proof. Which is not what we want!

(This is a very real problem if you are using Hugo. One can ask why not make the addition of tombstone to .proof p:last-child:after instead: the reason is that there is no guarantee that the final portion of the proof will be a paragraph element! For a short one paragraph proof, for example, Hugo's BlackFriday markdown parser will not insert paragraph tags.)

So instead in the stylesheet above, what we do is to wrap the proof text in flexboxes and create a second column (very skinny) that holds only the tombstone. This way regardless of the content of the proof a tombstone always appears at the end of the proof.

Theorems and friends

layouts/shortcodes/thmlike.html reads:

<div class="thmlike">
	<div class="thmheader">
		<span class="thmtype">
			{{ with .Get "type" }}
				{{ . }}
			{{ else }}
				Theorem
			{{ end }}
			&nbsp;
		</span>
		{{ with .Get "title" }} &nbsp;[{{.}}] {{ end }}
	</div>
	<div class="thmbody">{{ .Inner | markdownify }}</div>
</div>

and can be used in the markdown files as

{{< thmlike type="Conjecture" title="Riemann Hypothesis" >}}
This can be sometimes useful
{{< /thmlike >}}

The type parameter is optional. Without passing a parameter the code defaults to "Theorem" as the type. With some css magic (as can be seen above) all thmlike calls are automatically numbered from 1, regardless of type (my personal preference). The optional title parameter displays the title in brackets, and is useful for giving attributions.

Teaching History widget

The listing of teaching history is made using a modification of the Accomplishments widget. The modifications are mostly straightforward, with some changes to the data schema. The schema used is completely ad hoc and does not adhere to any standards. Items in the corresponding widget page (in my case I called it teachinghistory.md) are listed as

[[itemC]]
  school = "Michigan State University"
  date_start = "2019-01-08"
  term = "Spring"
  title = "Calculus II"
  url = ""
  coursenumber = "MTH133"
  sections = "22--28"
  description = "Co-instructing with [Mark Iwen](https://users.math.msu.edu/users/markiwen/)"

The date_start, school, title, and term parameters are required. Three classes of items are defined: itemC for courses in the current semester, itemPU for previously taught undergraduate courses, and itemPG for previously taught graduate courses. Keeping all three in the same file makes it easier to edit later on.

Potential improvements: add parameter for graduate/undergraduate, and filter accordingly. Also, add a date_end parameter and automatically determine which courses are currently in session.

Table of Contents

I don't quite like how academic sets the table of contents by default. First, it does not set anything at h3 level or higher (in markdown this is anything that is ### or higher. Secondly, I don't like the TOC heading to be so large.

To fix this, create in layouts/shortcodes/toc.html

<div style="padding-left: 2rem">
<h2 style="font-size:1.1rem;">{{ i18n "table_of_contents" }}</h2>
{{ $.Page.TableOfContents }}
</div>

to indent the TOC listing and make the words "Table of Contents" set in smaller font compared to the default h2 level.

To show the higher level headings, one needs to know how Academic hides them. It does so using CSS magic by setting those levels to have display: none. To fix this, one can overwrite it using a css plugin. First put into assets/css/tocoverride.css the following

#TableOfContents ul ul {
	display: block;
	padding-left: 1rem;
}

#TableOfContents ul ul ul {
	display: none;
}

.toc-top li a {
	font-size: 0.8rem;
}

This way the third level uls (corresponding to level h4 or ####) and higher will be omitted, but level h3 will be shown with an extra indent. To activate this css, make sure to edit params.toml in the config directory to include plugins_css = ["tocoverride"].