Hugo at ASLFri, Jan 15, 2016
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.
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
git clone email@example.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.
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 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 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
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.
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
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
#+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
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.
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.
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:
- 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
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
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
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.