Hugo at ASL

Fri, Jan 15, 2016

Overview

We are now using Hugo to produce the ASL web pages. It is written in Google’s GO language, and the web site is created almost instantaneously with a single executable that is available on linux and Macs.

You can write content in either markdown, org-mode, or raw html. I have tried to design the website so that the use of org-mode is very easy. Plus, with very few changes you can convert the org-mode files to produce latex output.

Website Organization

Hugo has a very simple file structure, but with fairly complicated rules for what files control what output. Here I only cover what I think you need to know to generate most output files we will need on the ASL website. Here is the top level of aslhugo, which you can clone using git clone git@github.com:strow/aslhugo.git.

  drwxrwsr-x  3 strow staff  102 Jan 12 14:58 archetypes
  -rw-r--r--  1 strow staff  431 Jan 14 11:44 config.toml
  drwxr-xr-x 14 strow staff  476 Jan 12 14:35 content
  drwxr-xr-x  2 strow staff   68 Jan 11 13:10 data
  drwxr-xr-x 17 strow staff  578 Jan 11 17:47 layouts
  drwxr-xr-x 13 strow staff  442 Jan 12 15:10 static
(  drwxr-xr-x 37 strow staff 1258 Jan 12 15:10 public  )

You will not see the public directory until you build the site, and if you always build it using “server” mode, you might not every see this directory. It contains the static website, which is built when you push the website git repo to maya (more on that later).

You generally only edit inside the “content” directory. If you learn more about Hugo and want to change some of the layouts please contact me, I’d rather this not be done without coordination.

Content Directory

You create your markdown or org-mode files here. At present the directories present under content are:

  drwxrwsr--   7 strow staff  238 Nov  1  2017 people
  drwxr-xr--   4 strow staff  136 Nov  1  2017 asl
  drwxr-xr-x   4 strow staff  136 Oct 21 11:39 help
  drwxr-xr--  18 strow staff  612 Oct 21 13:26 helppages
  drwxr-xr-x   7 strow staff  238 Oct 20 14:23 projects
  drwxr-xr-x   4 strow staff  136 Oct 21 15:06 reports
  drwxr-xr--  10 strow staff  340 Dec 12  2017 buczkowski
  drwxr-xr--  17 strow staff  578 Oct 22 10:26 hepplewhite
  drwxr-xr--   4 strow staff  136 Feb 20  2016 motteler
  drwxr-xr--  10 strow staff  340 Oct 21 15:47 sergio
  drwxr-xr-x   4 strow staff  136 Oct 22 09:17 strow
  drwxrwsr--  41 strow staff 1394 Oct 22 09:27 strowpages
  drwxr-xr-x   6 strow staff  204 Oct 21 16:11 telecons
  drwxr-xr-x 114 strow staff 3876 Oct 21 15:30 oldtelecons
  drwxr-xr--   6 strow staff  204 Sep 27  2017 links

You should put all your pages under your name, or, under your namepages, ie =strow= or =strowpages=. In the beginning I would not use the equivalent of strowpages unless you want to have your own pages ordered by a tag. (It’s easy.)

Right now there are three private directories, “asl”, “telecons”, and “projects”. =asl= is for somewhat temporary documents we need to look at but want to keep private. =projects= is for project sensitive data like grant funding, etc. that is more permanent. =telecons= hold our weekly telecon text. If you want to put something under one of these directories just go ahead and put your source code there. You can use any directory depth you like, but you

The menu is now the same now for all content.

Content Directory Types

There are two basic structures for directories. One is called a “leaf” directory, the other a “bundle”. This is a recent change to Hugo, and although it broke some of our stuff, it actually created the ability to do what we want, and my kludge to do that in the past is no longer needed. This only affected Chris and me.

Technically there are also plain vanilla “sections” (leaf and bundles directories are also sections, don’t ask). If a directory has no _index.html or index.html file it is “plain vanilla” and Hugo will list the titles of these files under asl.umbc.edu/yourname. But, you can’t have figures in your directory referenced by these files, so they are kinda useless except for the most simple things.

Leaf directories

Leaf directories contain files and directories of files (.org, .md, .html) but also have an _index.html. The only thing that buys you over a plain vanilla directory is that you can put some header information in the top of the file. Here is a sample _index.org file that just puts a header “L. Strow Work Page” at the top of the web page, it will be followed, automatically, by a listing of page titles.

#+OPTIONS: h:4 toc:nil num:0
* L. Strow Work Page

Bundle directories

This is what you generally want to use, and is what caused us a lot of headaches when it did not exist before!!

If a directory contains index.html, then it is a bundle directory and your source code is in that file. BUT, now you can fill that directory, and it’s subdirectories with figures, just like you do for LaTeX, and the org source for LaTeX works with Hugo, which is really nice.

content/strowpages for example is a leaf directory. The subdirectories of strowpages are all bundle directories. Eventually I will probably turn all content in strowpages into bundle directories.

For example, pdf_airs_vs_cris is a bundle directory under strowpages. When you look at asl.umbc.edu/strowpages/ the automatic directory listing will show the leaf directory titles and any bundle directory titles under strowpages.

Content Files

A particular web page is created by creating either a markdown or org-mode file. If you write in markdown (and use the file suffix .md) Hugo will automatically create a web page from that file. If the file name is /content/sergio/oem_cloudy_iasi.md it will have the URL https://asl.umbc.edu/sergio/oem_cloudy_iasi. Note, no .html on the end, Hugo puts each page in a separate directory, and the content itself in in the file index.html in that directory.

To create the file, you can either copy the template from another file, or execute the command hugo new sergio/oem_cloudy_iasi.md. You could put .org on the end instead of .md if you are thinking you will edit in org-mode. This command puts the file where you told it to, and adds some instructions to the top of the file, as seen below.

#+OPTIONS: h:3 toc:nil num:2
#+BEGIN_EXPORT HTML
+++
title = "Oem_cloudy_iasi"
date = 2018-10-22T11:27:52-04:00
author = "Sergio"
comment = true
+++
#+END_EXPORT

You could do this by hand instead, but you need to be very careful to follow the Hugo date format, and this command takes care of that for you. If you are using markdown, then just start writing your content after this header information. Note that Hugo tries to come up with a title from your file name. Generally you will edit that with something nicer. When Hugo lists the files in your directory, it uses this “title” entry for the listing, not the file name.

New Keyword Functionality

The help = ["Some key"] configuration says this file should be highlighted on our ASL Help Page under heading “Some key”. Other examples might be report = ["AIRS"] which will place your document in our public area under heading AIRS, which will be seen at asl.umbc.edu/reports/. Basically you can use the taxonomies “help”, and “report” and assign any key to these that you want. To create a new taxonomy (not a new key), you edit config.toml. You likely don’t want a new taxonomy unless you want to have your files sorted by subject, like I am doing under content/strow.

The web pages that list the key values are automatically written, with links for each key to another page that lists all the files with that key. For example, the help page listings (of keys) are at https://asl.umbc.edu/help. Then you click on the URL that goes with a key, and you get a listing of all the web site pages that have that key set. It’s easier to understand this by just looking around.

Relative Links

You can still use relative links for information you want to link to on the ASL web site. The main thing to remember is that you need an extra ../. So if you are editing a file at /content/sergio, and you want to link to a file (or directory) strowpages/pdf_airs_vs_cris, you would write this in your file as ../../strowpages/pdf_airs_vs_cris. Works the same in Markdown as org-mode.

Workflow

In general, your workflow is as follows once hugo is setup and you have cloned the aslhugo repo.

• Update aslhugo: git pull origin master
• Start hugo for previewing: hugo server
• Edit your files and see how they look
• Once you are OK with your page
  • Pick up any change from others: git pull –rebase (which will generally work without intervention)
  • Add you file to git: git add (yourfiles)
  • Commit: git commit
  • Push to Github: git push origin master
  • Push to maya (which makes your changes live): git push deploy master
    

If you don’t want one of your new pages published, just put draft = true in the config section of your source file. When you do this, the page will not show up in our website, but it will show up on your home machine using the hugo server previewer. (Note, the previewer serves up the website on your local browser at http://localhost:1313). Better yet, when you change something, the pages automatically update!

Generating Website Pages with Org-Mode

Emacs org-mode creates far better html than markdown, and creates extremely good latex code. Markdown hardly supports tables, while you can create fairly complex tables with org-mode. However, org-mode requires a few extra steps to create a Hugo webpage. Hugo works by looking at your website configuration, and then builds pages by encapsulating the markdown to html output into those pages. If Hugo sees a file with an “.html” suffix, and that file contains Hugo mark-up configuration statements at the top of the file, it will also encapsulate that file into the final website.

You can do this with org-mode with a minimum of three other lines. Below is the general form of the org-mode file:

#+OPTIONS: h:3 toc:nil num:3

#+BEGIN_EXPORT HTML
+++
title =  "Org-Mode for Hugo Web Pages"
date  =  "2016-11-15"
author = "L. Larrabee Strow"
+++
#+END_EXPORT

The top line is standard org-mode instructions, the key is you must include toc:nil or you cannot export correctly to Hugo. (This means do not produce a Table of Contents, which we can do with Hugo quite nicely other ways.) The two #BEGIN_EXPORT commands tells org-mode to put the lines inbetween into the html file. You then create the html file with the commands C-e C-b h h. In words this command says (1) C-e enter the org-mode exporter, (2) C-b only output the html body with no header information, (3) h h says select the html export and save it as an .html file.

In summary, you only need to enter three special org-mode lines to your file, and then do the equivalent of three keystrokes, and you are done.

You should now read the posts on the syntax for writing markdown and org-mode files, which is mostly about math, code blocks, figures, and tables.