Building Static Sites with Hugo

What is a static website?

Made up of HTML, CSS, & JavaScript
No back-end scripting languages, databases, or CMS
Displayed to user as it exists on the server

What is a static website generator?

Template language & markup language
Compiles into HTML/CSS files
Built-in server for testing
Many options - 182 on staticgen.com
Most popular is Jekyll (built in Ruby)

Benefits

Performance & speed
Less technical maintenance
Less resource intensive
Security benefits
Version control
Simple hosting, e.g. Github pages, OLRC

Drawbacks

Learning curve
No editing environment (but there are options)
No dynamic elements

Static site generators are not without their disadvantages. They don't have an admin interface or an editing environment like a content management system does, so there's some technical skill required to update the site. There are tools being developed to improve on this, but at this point there's still some technical knowledge needed to do content updates. At Scholars Portal, we've been using the editor built into Github for some basic content editing. Since some technical skill is required, there can be a bit of a learning curve involved with static generators. You need to understand some HTML and CSS, some command line and git basics, and if you want to do a lot of site customization, you'll need to learn the templating language that's being used. These may be barriers for and less technical people involved in the web development process. Finally, because they are static, static sites don't have the option for dynamic elements, like user accounts or other kinds of interaction with a user.

Hugo

gohugo.io

Why Hugo?

Speed
Less dependencies
Built-in multilingual functionality
Integrations (Google analytics, formspree, disqus)

Basic Hugo workflow feat. maps!

ocul.on.ca/topomaps | github.com/scholarsportal/historical-topos

Install

snap package, homebrew, single binary download

Add a theme

themes.gohugo.io/hugo-creative-portfolio-theme

a screenshot of the hugo creative portfolio theme page on hugo's website

Add a theme


cd themes
git clone https://github.com/kishaningithub/hugo-creative-portfolio-theme.git

Theme example site

Many themes have an example site that you can copy to get started


cp -r themes/hugo-creative-portfolio-theme/exampleSite/* .

Built-in development server

Configuration & Content

The configuration file (toml, yaml, or json) contains menus, metadata, etc.
Content lives in the content/ and data/ folders
Assets (e.g. images, custom CSS & JavaScript) live in static/

config.toml


baseurl = "http://ocul.on.ca/topomaps/"
theme = "hugo-creative-portfolio-theme"
# Enable comments by entering your Disqus shortname
disqusShortname = ""
# Enable Google Analytics by entering your tracking code
googleAnalytics = "UA-9010354-11"
canonifyURLs = false
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false

[params]
logourl = "http://ocul.on.ca"
style = "blue"
email = "topomaps@scholarsportal.info"

[params.social]
github = "https://github.com/scholarsportal/historical-topos"
email = "topomaps@scholarsportal.info"

[Languages]
[Languages.en]
languageName = "English"
title = "Historical Topographic Map Digitization Project"
languageCode = "en"
weight = 1
logo = "img/ocul.png"
logoalt = "Ontario Council of University Libraries"
[[Languages.en.navlinks]]
name = "Home"
url = ""
[[Languages.en.navlinks]]
name = "About the Project"
url = "about-project/"
[[Languages.en.navlinks]]
name = "About the Maps"
url = "about-maps/"
[[Languages.en.navlinks]]
name = "Collection Highlights"
url = "highlights/"
[[Languages.en.navlinks]]
name = "Using the Maps"
url = "using-maps/"
[[Languages.en.navlinks]]
name = "Full Collection"
url = "collection/"
[[Languages.en.navlinks]]
name = "FAQ"
url = "faq/"
[[Languages.en.navlinks]]
name = "Contact"
url = "contact/"

[Languages.fr]
languageName = "Français"
title = "Projet de numérisation de la carte topographique historique"
languageCode = "fr"
weight = 2
logo = "img/cbou.png"
logoalt = "Conseil des bibliothèques universitaires de l'Ontario"
[[Languages.fr.navlinks]]
name = "Accueil"
url = "fr/"
[[Languages.fr.navlinks]]
name = "À propos du projet"
url = "fr/about-project/"
[[Languages.fr.navlinks]]
name = "Au sujet des cartes"
url = "fr/about-maps/"
[[Languages.fr.navlinks]]
name = "Points saillants de la collection"
url = "fr/highlights/"
[[Languages.fr.navlinks]]
name = "Utiliser les cartes"
url = "fr/using-maps/"
[[Languages.fr.navlinks]]
name = "Parcourir la collection au complet"
url = "fr/collection/"
[[Languages.fr.navlinks]]
name = "FAQ"
url = "fr/faq/"
[[Languages.fr.navlinks]]
name = "Nous contacter"
url = "fr/contact/"

Content creation

Hugo content is written in Markdown, with added HTML


+++
date = "2017-03-16"
title = "Using the Maps"
+++

<ul class="contents">
	<li><a href="#finding-maps">Finding maps</a></li>
	<li><a href="#exploring-maps">Exploring maps</a></li>
	<li><a href="#downloading-maps">Downloading maps</a></li>
	<li><a href="#advanced-searching">Advanced searching</a></li>
</ul>

[Scholars GeoPortal](http://geo.scholarsportal.info) is an online geoportal that allows users to find and download geospatial data and maps. Using the GeoPortal and the built-in map index navigation, users can view map availability by location, and, add maps to the map viewer to explore online. The GeoPortal also supports features to layer multiple maps, and layer other data to visualize changes over time. Maps can be downloaded for any purpose and available in GeoTIFF or JPG formats. Follow the steps below to learn more about how to access and use the collection in the GeoPortal.

To search for maps directly by place name without entering the GeoPortal, go to [_Full Collection_](../collection/).

## Finding Maps

### Using the index

The first step to accessing the historical topographic map collection is to locate and use the index navigation aid. There are two sets of historical topographic map collections available in the Scholars GeoPortal, each with their own index map for navigation, one for the 1:63,360 and 1:25,000 scale map sets. Using the index navigation, you can view map availability by selecting the area of interest found on the map. 

In Scholars GeoPortal, maps are available through an interactive online index display. To access the map indexes for different map scales, go directly to the Scholars GeoPortal:

- [1:63 360 Index Navigation](http://geo.scholarsportal.info/#r/details/_uri@=564032357&_add:true)
- [1:25 000 Index Navigation](http://geo.scholarsportal.info/#r/details/_uri@=847590539&_add:true)

You should now be presented with the index navigation aid to select maps of interest. 

<img class="img-responsive using-maps" src="../img/usingmaps/Figure-3.PNG" alt="Screen capture of the 1:63,360 index map, loaded on the map viewer in the Scholars GeoPortal.">

Customization

We can add custom CSS or JavaScript, or override the existing templates
Templates determine the layout of the site
Hugo templates use the Go templating language

Go templates

Building the site

Build the public files, then copy them to the web server


cd topomaps
hugo


404.html
▸ collection/
▸ en/
▸ img/
▸ maps/
▸ about-maps/
placenames.json
▸ faq/
index.html
sitemap.xml
▸ about-project/
▸ contact/
▸ fr/
index.xml
▸ tags/
▸ categories/
▸ css/
▸ highlights/
▸ js/
▸ using-maps/

Static Website Generators

What is a static website?

What is a static website generator?

Benefits

Drawbacks

Hugo

Why Hugo?

Basic Hugo workflow feat. maps!

Install

Create the site

Add a theme

Add a theme

Theme example site

Built-in development server

Configuration & Content

config.toml

Content creation

Customization

Go templates

Building the site

Questions?