I am moving the PSICE site to a Hugo-based system. Hugo is a so-called "Static Site Generator" in which one writes the content as a text file and Hugo generates the HTML code to put on the server.

Overview of the pages generated by Hugo

The theme is stolen from RPAL at Cornell, who have kindly shared their setup. The look is driven by config.toml.


## config.toml 

title = "PSICE"
baseurl = "https://www.psice.psu.edu//"
languageCode = "en-us"
theme = "ghostwriter"
# ...removed some lines

[Params]
    intro = true
    headline = "Ice and Climate (PSICE)"
    # ...removed some lines

[[menu.main]]
    name = "Home"
    url = "/"
    weight = 1

[[menu.main]]
    name = "News"
    url = "/news/"
    weight = 2

# ...removed some lines...

[[menu.main]]
    name = "Contact"
    url = "/contact/"
    weight = 6

Each [[menu.main]] entry will generate a new page and a new menu item in the navigation bar (the ordering of the nav items is based on the weight). The content for that page is in the url entry. Hugo will look for either a file with that base name or a directory with that name.

If there is a file (with an extension of either md, for markdown text or org for Org-mode text), then that file will be parsed for any markup instructions and rendered nicely on the page. (Markdown and Org-mode are ways to shortcut and simplify formatting of text. Google is your friend...).

If there is a directory with the url name in the content directory, then Hugo will process each file in that directory and display them. Here is where it could get hairy because Hugo can render those pages in many different ways that you can customize.


├── config.toml
├── content
│   ├── about.org
│   ├── contact.org
│   ├── news
│   │   ├── GMT.org
│   │   └── migrating-to-hugo.org
│   ├── people
│   │   ├── brad.md
│   │   ├── byron-parizek.md
    ...

Layouts

The theme layout can be overridden by files in the directory /layouts.


layouts/
├── 404.html
├── index.html
├── partials
    # ... more on this directory later
├── section
│   ├── data.html
│   ├── news.html
│   ├── people.html
│   ├── projects.html
│   ├── pubs.html
│   ├── pubs.html~
│   └── research.html
└── shortcodes
    # ... more on this later

The Front Page.

Here is what was in config.toml for the home page:


[[menu.main]]
    name = "Home"
    url = "/"
    weight = 1

Because the url field is empty, Hugo will search for the file to use in a number of places, starting with my /layouts page, where there is indeed an index.html file. This file is a template that Hugo will use to render the actual Home page.


<!-- /layouts/index.html -->
{{ partial "header.html" . }}

<div id="main-body" class="page-content">
  <div id="about-blurb" class="blurb">
    {{ range where .Pages "Type" "about" }}
    {{ .Content }}
    {{ end }}
  </div>

  <h1 class="post-title"> News </h1>
  <ol class="post-list">
    {{ $pag := .Paginate (where .Data.Pages "Type" "news") }}
    {{ range $pag.Pages }}
    {{ partial "news-stub.html" . }}
    {{ end }}
  </ol>

  <div class="post-navigation">
    {{ partial "pagination.html" . }}
  </div>
</div>

{{ partial "footer.html" . }}

Here is a screen capture of the front page.

Hugo Templates

The simplest is the yellow block, which was generated by


  <div id="about-blurb" class="blurb">
    {{ range where .Pages "Type" "about" }}
      {{ .Content }}
    {{ end }}
  </div>

Within a div block, there is a Hugo function range ... end.

range is a for loop that finds all the pages whose Type is about. Those pages that are found are processed by the command inside which is simply {{ .Content }}, which emits the contents of those pages.

Which pages have Type of about? Metadata!

Every file that is processed by Hugo has front-matter that contains meta-data about the file. At a minimum, it must include a title and a date. It can also include other things. Here is the start of about.org, which includes a metadata entry #+TYPE: about which Hugo uses. The {{ .Content }} of this file is the remainder of the file, which is rendered to HTML for display.


#+DATE: 2017-01-25T00:25:59-05:00
#+TITLE: About PSICE
#+TAGS: 
#+AUTHOR: 
#+DESCRIPTION: Who we are and what we do
#+TYPE: about

Penn State Ice and Climate is an interdisciplinary group of
researchers from across the university dedicated to a better

Partials

The material outlined in red was generated by


{{ partial "header.html" . }}

which uses the file /layouts/partials/header.html as a template. This file has all the required HTML header stuff, as well as lots of Hugo-specific functions that generate the navigation bar, the social-media icons and links, etc.

News

And the orange section is generated by


  <h1 class="post-title"> News </h1>
  <ol class="post-list">
    {{ $pag := .Paginate (where .Data.Pages "Type" "news") }}
    {{ range $pag.Pages }}
    {{ partial "news-stub.html" . }}
    {{ end }}
  </ol>

Here are the files in /content/news. The {{ .Paginate ... }} command will group the pages of Type equal to news in sets of 10 (by default - this can be changed in config). The range ... end loop will run the partial function news-stub.html on each file. news-stub will print the title and date.


│   ├── news
│   │   ├── GMT.org
│   │   └── migrating-to-hugo.org

Types part 2: each file in the directory content/news/ has Type of news even if there is no metadata tag...

And here is news-stub.html template with a lot of extraneous stuff stripped out. It generates an html <li> tag (unordered list) for each file. It makes an <a> link. The contents of the link are the title ({{ .Title }}) and a time. The time is formatted twice: once for the <time> tag (with a datetime property in the expected format) and once to be displayed (Published {{ .Date.Format "Mon, Jan 2, 2006" }}).

The Date.Format function is given a format that it can cleverly figure out ("2006-01-02" and "Mon, Jan 2, 2006" are both just hints to Hugo on how you want the actual date formatted).


<li ...>
    <a href="{{ .Permalink }}" ...>
        <h4 >{{ .Title }}</h4>
        <time datetime="{{ .Date.Format "2006-01-02" }}">Published {{ .Date.Format "Mon, Jan 2, 2006" }}</time>
    </a>
</li>

And here is the HTML that was generated (with all the extra cruft):


<li class="nomove blurb-container" itemprop="blogPost" itemscope="" itemtype="https://schema.org/BlogPosting">
    <a href="http://localhost:1313/lab-site/news/gmt/" class="news-post" itemprop="url" title="Go to post detail">
        <h4 class="post-stub-title" itemprop="name">GMT</h4>
        <time class="post-stub-date" datetime="2017-07-16">Published Sun, Jul 16, 2017</time>

    </a>
</li>

More

Part Two, on how to customize pages, or click on the Tagged: hugo link below.