From Spreadsheet to Multilingual Website Using Oxygen XML Editor & Hugo Static Site Generator

Welcome to the workshop website for From Spreadsheet to Multilingual Website Using Oxygen XML Editor & Hugo Static Site Generator.

Here you will find all the information about the workshop and instructions to help you get started.

This workshop will use a subset of data and a simpler practice website from Recetas de las Américas, a bilingual website made with Hugo by Sarah Tew and Melissa Jerome.

My contact: sarahetew@ufl.edu

This tutorial is made for Windows and may need adjustments for macOS.

Tutorial GitHub: https://github.com/SarahTew/dlf-hugo 

Table of Contents

Installing Hugo

For Windows:

1. Go to the GitHub for Hugo Releases

2. Scroll to the Assets for the latest version.

3. Click "Show all 23 assets" at the bottom

4. Download the appropriate zip file: hugo_0.119.0_windows-amd64.zip (Note: This link will take you straight to the download)

5. Open the folder (it will be zipped, that's fine you can extract or not, it doesn't matter)

   • You should have 3 files in there: hugo.exe; LICENSE; and README.md

6. Create a "Hugo" folder (capitalization is important!!) on you C: drive

7. Inside the Hugo folder create a folder called "bin" (capitalization is important!!)

8. Put all three files: hugo.exe; LICENSE; and README.md inside the "bin" folder

9. Open the Command Prompt

10. In the Command Prompt type: set PATH=%PATH%;C:\Hugo\bin and hit enter

11. Test that Hugo was installed correctly : type hugo version  into the Command Prompt and hit enter

    • If installed correctly you should see a long line of text that starts with hugo v0.119.0

    • If not installed you should see an error about hugo not being a recognized command

For Mac:

1. I recommend installing with a package manager like homebrew.

Installing Oxygen

1. Request a free trial license

2. Follow Oxygen's Installation Instructions

Download the Workshop Materials

Download the UF-Hugo-Training folders from https://github.com/SarahTew/dlf-hugo 

Unzip and save the folder on your C: drive

Use Hugo to Create a Local Server

Creating a local server

Creating a local server will allow you test your site as you make changes.

1. Open the Command Prompt/Terminal

2.  Navigate to the Hugo Test Site folder through the command prompt using: cd

   • Use cd.. to go up a directory

   • Use cd [name of folder] to go into a directory

3. Once you're in test-site📁, type hugo server into the command prompt

   • If successful you will see a message that starts with Start building sites … and then a table of what it built 

   • If unsuccessful you will get an error that tells at which part of the building process it ran into a problem. You will need to fix this before it can build the site.

4. Open your internet browser and go to localhost:1313

   • If correct, you should see your website

   • If incorrect, you will not see anything on first load. If you make a so-called fatal error while developing your website, the localhost:1313 page will crash and display the same error message that's in the Command Prompt.

   • Check your website out! Check to make sure the recipes are there and the content is in the appropriate language

You must leave the local server up while you are working on your site.

• If you close the Command Prompt window you started from, you will end the server and no longer see your site.  When you open a new Command Prompt you will have to navigate back to the test-site directory

• You can end the server in the Command Prompt with Ctrl+C and stay in the test-site directory

• If you close your browser only, nothing will happen. Your server is still running.

Explore the Files

test-site📁

test-site📁 Is where everything Hugo needs to build your site is stored. 

source-data📁 is where you'll store the materials you need to process your original content into forms Hugo can use.

Hugo uses the other folders to create your website. It requires specific file structure and naming so do not rename or move folders.

We'll go more into what's in test-site📁  more in-depth later in the tutorial.

The Spreadsheet

Find the trial_data spreadsheet in dlf-hugo 📁 --> training materials 📁 --> trial_data.xls📄

Open it to take a look.

Features of the Spreadsheet

• Saved as an xls (old version of Excel files)

  • Why: Easier import into Oxygen later

• Column headings: No Spaces!

  • single-word headings and _ instead of space

• Only one row of headings

• Lists of things are in one cell together separated by semicolons

  • eg. chayote; cornstarch; sugar; egg; milk; salt; raisins; butter; cracker meal

  • eg. Split the chayotes lengthwise and boil.; When they are soft take out the pulp and mash well.; Beat the yolks with the sugar, add salt, and cornstarch, milk, mashed chayotes, butter and potatoes; Put on the fire and cook until thickened like a cream; Fill the rinds with the cream and sprinkle cinnamon on top.; Bake for ten minutes.

• Only some fields have English and Spanish versions

  • Fields that stay the same across both langauges, like ID, the newspaper it's from, and the URL don't need translations

Explore Oxygen

Starting Oxygen

The Trial License Key

• When you first open Oxygen, you may need to enter a license key.

• If you are borrowing a laptop today, check the desktop for a text file  with the license key

• If you are using your own laptop, enter the key you requested from Oxygen if you have not already done so.

Making a new Oxygen Project

You will do all the work to develop your website in Oxygen. The Oxygen Project file helps you manage all your files.

Whatever you do in Oxygen will be reflected in your regular computer files and vice versa.

1. Click the "Project" tab at top left.

2. Click "New Project"

3.  A file will show up. Navigate to  test-site📁

4. Name your project

   • The name can be anything; I'm using UF_Hugo

5. You should now see the blue "Project" tab on the left with test-site📁

6. Double click or use the small arrow on the left to open test-site📁

7. You should see all the folders inside test-site📁

Importing the spreadsheet as an XML

You must import the spreadsheet in order to start working with it in Oxygen.

1. Click on the source-data📁

2. You will see more folders and some .xsl files. Ignore for now.

3. Click the "File" tab in the upper left.

4. Click the file folder icon to open the file navigator

5.  Go to training materials 📁 --> trial_data.xls📄

6. In the "Available Sheets" indow select "recetas"

7. Import criteria

   • Check the box that says "First row contains field names"

   • Uncheck the box that says "Import formatted data"

   • Use the horizontal scroll to go to the end and check for any blank columns

     • See the blank "Heading 16", "Heading 17", "Heading 18" columns.

     • Click the <> next to the heading name until it's an "x". This removes it from the import.

     •  You can use this to delete any extra columns for your data that you don't want to import for use in your website.

   • Check the box that says "Open in Editor"

   • Don't check the box that says "Save in file" and click the small folder icon

8. Click Import

   • Oxygen should open trial_data.xml📄 in the viewer

XML

Take a look at the XML and how it compares to the spreadsheet.

XML puts tags in your text content to structure the data.

Save the new xml in dlf-hugo📁 --> test-site📁 --> source-data📁

1. • • Name the file trial_data

Check that you can now see the trial_data.xml📄 in the project pane.

You will transform this xml into everything Hugo needs in order to build the website:

• Markdown files

• HTML partials files

You will transform them using XSLT and Oxygen's built-in tools for transforming XML into other formats.

Transformation scenarios

In source-data📁 you have 4 .xsl files I have already written for you.

These files will be used to transform trial_data.xml📄

Setting up a Transformation scenario

1. Right click on trial_data.xml📄 in the project pane

2. Hover over "Transfrom" in the menu

3. Select "Configure Transformation Scenario"

4. Click New

   • New XML transformation with XSLT

5.  New Scenario window

   • Name the scenario table2md (I name my scenarios after the sheet I will use for them to help me keep them straight)

   • Check that the XML URL field says ${currentFileURL} (this is autopopulated)

   • For XSL URL click the small folder and select table2md.xsl📄 in source-data📁

   • Output tab: If you want to save them to a separate folder for markdowns: make sure "Save as" is selected and ${pdu}/source-data/md/${cfn}.md is listed in the field.

6. Click "Apply Associated"

7. You should see new markdown files now in source-data📁

Open one of the markdown files. How does to compare to the spreadsheet? To the XML?

Creating the English markdown files

We're going to copy and edit table2md.xsl📄 it so it will create English markdown files.

1. Right click on table2md.xsl📄 in the Project pane. Copy and paste it in the same folder. Rename the copy table2md_en.

2. Open table2md_en.xsl📄

3. Edits:

   • Line 7:  add .en to the markdown file name : <xsl:result-document method="text" encoding="utf-8" href="{id}.en.md">

   • Add _en to the title, tags, ingredients, and course selections in blue

   • There are two of each in this XSL; try using Ctl + f to do a find and replace in Oxygen

   • Line 54: add .en to the html file in the readFile line: <xsl:text>{{&lt; readFile file="./html/recipes/</xsl:text><xsl:value-of select="id"/><xsl:text>.en.html"&gt;}}</xsl:text>

4. Save table2md_en.xsl📄

5. Create a new transformation scenario for your English sheet and run it.

   • Save as file path: change to  ${pdu}/source-data/md/${cfn}.en.md

6. Check your new markdown files.

You can run multiple transformation scenarios at a time. Once you have both scenarios made you can select them both and generate the English and Spanish in one command.

Creating the Spanish HTML partials

Oxygen got picky with me and  my html scenario didn't work as cleanly as the markdown one and I still haven't figured out why. When that happens, don't panic! Work around it!

Because of this issue, we need to split the XML into individual recipes.

1. Configure and then run a transformation scenario with split.xsl📄 to split the trial_data.xml📄 into separate xmls for each recipe.

2. Select all of the new xmls and then configure and run xml2html on them

   • Output tab: make sure the Save as button is checked and it has ${pdu}/source-data/html/${cfn}.html in the Save as field.

3. Your new htmls should populate in html📁 inside source-data📁

Creating the English HTML partials

We're going to copy and edit xml2html.xsl📄 to to create English html partials.

1. Create and open a copy named xml2html_en📄

2. Edits:

• Line 22: Remove _en from ingredient_list_en

• Line 23 remove _en from directions_en

• Line 29: Add _en to field name <xsl:template match="ingredient_list_en">

• Line 31: Change spelling to English Ingredients

• Line 35: Add _en to field name <xsl:template match="directions_en">

• Line 37: Change spelling to English Directions

3. Configure and run the xml2html_en scenario

   • Don't forget to change the Save as field

4. Check your files.

   • FYI: Oxygen will overwrite files with the same file name; if you didn't switch the Save as field you might get English files under the Spanish name and vice versa

Congratulations! You've transformed your spreadsheet into Markdown and HTML and are now ready for Hugo to build your site!

Adding content to the test site

You need to move md and html files into Hugo's content folders to add them to the site. 

1. Select and drag all the html files (English & Spanish) from source-data📁-->html📁 to content📁-->html📁-->recipes📁

2. Select and drag all the md files from source-data📁-->md📁 to content📁-->recetas📁

Explore Hugo

Understanding file structure

Hugo requires a particular file organization to run correctly. Certain folders are mandatory to have, even if you do not use them.

The easiest way to start making a Hugo site is to adapt a very basic pre-existing hugo site.

• You can use test-site as the basis of your first project

• You can use a Hugo theme made by someone else. This will include a theme and an example site for you to adapt. A simpler theme is much easier to adapt.

• You can also generate a blank site from the command prompt but you will also have to generate a new theme and it is more complicated.

Themes vs. site

Hugo has a hierarchical file structure so some folders and files override others.

The theme is a the basic skeleton of the website and gets supplement and/or overwritten by other folders in what I call your "site".

The test-site's theme, MyTheme is very basic.

Go to MyTheme📁 --> layouts📁

• You'll see two folders, _default📁 and partials📁

  • _default layouts tell Hugo how to layout the main parts of your different webpages

  • partials tell Hugo how to layout the parts that appear on every page like navigation bars and footers and anything else you want appearing across the site in the same way.

Go to  layouts📁 in your main site, outside of the theme.

• You'll see another _default📁 and partials📁 as well as recetas📁 and shortcodes📁

  • Hugo ranks files in this layouts📁 higher than files with the same name in the MyTheme📁 --> layouts📁 and will use these on the site

  • Why is this important: You can get a basic theme for your site then make all the changes you need in your site folders without having to worry about messing with the theme.

  • The recetas📁 contains the layouts for the recipe pages.

Layouts vs. Content

• Within your site, there is a  layouts📁 and a content📁

  • Layouts give Hugo instructions on where to find the parts it needs to assemble your website and instructions on how to arrange those parts on the website

  • Content are the parts Hugo will assemble.

    • Recipe text

    • Images & PDFs

    • Custom CSS

Markdown & HTML

• Markdown files contain metadata about each page

• HTML files are partial and provide some, but not all of the content that goes on each recipe page

• Layouts tell Hugo how to assemble the HTML partials.

• All of your content items must have their own markdown files.

Multilingual Websites

• Hugo allows you to build a multilingual website without other software or plugins

• You must structure your files correctly to do this

  • In the test-site, Spanish is the default language so the English files must have have an .en added. Spanish files can have nothing or .es

    • eg. Spanish markdown file: r01.md ; English markdown file: r01.en.md

    • eg. Spanish recipe page layout: single.es.html ; English recipe page layout: single.en.html

• This is one of two ways to structure files for a multilingual website

• See their Multilingual Mode Instructions on their website

• You can also find good information about how to make a multilingual site from this blog

• Hugo does NOT translate your content for you. You must provide your own translations.

The Config file

• This is the most important file for your website

• baseURL

  • This is the first line of your config file. 

  • This tells Hugo how to write all the URLS it needs for your site and all the links in it

  • You must enter the final URL for your project here. If you enter it incorrectly, your site will look great on localhost:1313 but non-existant once you start hosting it on the web.

• Theme

  • Make sure this matches the name of the theme you are using. If this is not set you will get an error when you try to build your site

• Languages

  • Make sure to set a default language

  • Use the ISO 639-1 Code for the desired languages

    • List of language codes (use second column)

• Taxonomies

  • Taxonomies are part of what makes Hugo really amazing and great for DH library projects

  • Taxonomies are essentially metadata fields that you tell Hugo to pay special attention to and keep track of for you. You can use them in your site to automatically create lists.

    • eg. Go to http://localhost:1313/en/ingredientes/chicken/ 

    • Because I have an "ingredientes" taxonomy listed in my config file and a default list template, it generates this page. 

    • You can also use this capability to call lists and terms throughout your website, not just on a list page. An example of this is https://recetas.domains.uflib.ufl.edu/en/filtro/

      • The left side of this filter page was made by telling Hugo to go pull every term in the taxonomies for dietary restrictions, course, and ingredients.

      • Hugo knows which recipe contains each term because of the markdown files.

      • The right side of this page was made with a JSON file using Hugo's built-in data folder.

Editing your site

Edit your English Homepage

Go to layouts📁-->index.en.html📄

Add some text to your English homepage and save.

Check your localhost:1313 to see your changes.

Edit the CSS

Go to content📁-->css📁 --> style📄

Change the color of the links in the navigation menu when you hover from pink to  blue.

Hint: find the section labeled "Hyperlinks"

Check your localhost1313 to see your changes.

Troubleshooting: If you are making changes to the CSS and nothing looks like it's changing in localhost:1313, test something you KNOW you can see and are doing correctly. 

If you can see that change then you know that what you were trying to do before is wrong. 

If you cannot see that change you know you should, it might be browser caching. In this case, clear your browser history of cached files and/or open localhost:1313 in a new browser.

Adding PDFs

Go to one of the recipes and click the pdf link.
You should get an error.

Add the pdf files into content📁-->pdf📁

Check localhost:1313 and click the link now to see your changes.

Adding Recipe Images

Add the image files into the content📁--> images📁--> recetas📁

Add these lines of code to your single.es.html📄 and single.en.html📄 templates

[START]

<div class="col-image">

{{$path := .Page.Params.jpg}}

<img class="recimg" style='height: 100%; width: 100%; object-fit: contain' alt="imagen de receta {{ .Params.title}} en el diario " src= {{ printf "../../images/recetas/%s" $path | urlize | absLangURL}}></img>

</div>

[END]

Change the words in bold for the English version: alt= "image of newspaper recipe {{ .Params.title}}"

Generating your site

Generate your site once you satisfied with your edits and ready to share it publicly. 

One command will generate all the public files for your site. These are the static files you can take to wherever you are hosting your project.

1. Close the local server.

   • Ctrl+C will kee you in the same directory

   • You can close the command prompt but then you will have to navigate back to test-site📁

2. Verify you are in test-site📁

3. Type hugo and press enter.

4. You should see a similar table to when you made the local server with hugo server  earlier.

   • If unsuccessful, there will be an error message specifying where and why Hugo got stuck and was unable to keep building.

5. Verify that a new public 📁 is now in test-site📁

6. Take a look at public 📁

   • How does it compare with the test-site📁 directories you worked with in Oxygen?

Hosting Your Site

This tutorial isn't going to go into hosting.

Recetas is hosted by LibDomains.

Whether LibDomains or another hosting site, you will transfer the contents of public 📁 on your machine into the public html folder of your website. 

Once you transfer the files, the site is done and will not change unless and until you upload new public files. This makes a static site much cheaper and easier to maintain.