Skip to content

IDeA Labs Website

This page discusses the tech stack used to generate the labwebsite and how to modify it's contents.

Overview

The website is hosted on the lab web server, which uses Caddy as the webserver. Follow the instructions on the web server page to access the server. On the server, the website contents can be found at /var/www/website. The source code for the website is hosted in the GitLab repository at https://gitlab.com/idealabs/website, and the web server is configured to automatically pull any changes from the master branch, build the website using the static website generator Hugo, and then immediately begin serving the updated contents. It should be fairly quick to reflect any changes made, and though the initial configuration is a bit complicated, it allows all of this material to be stored in plaintext by a version control platform and be presented in a easy to use website. Hugo is a static website generator, and by that I mean that it takes a set of text files, a theme template, and some configuration information, and then generates a static website that doesn't need anything except a public IP address and a webserver to be viewed. No database, no interpreters, nothing.

Note

At the time of writing, Hugo has not reached a stable version number and future changes could break this website. The webserver currently has a Hugo executable that was manually downloaded, but if you attempt to upgrade, be aware. Also, you need to use the extended Hugo binary, since we process SCSS.

Editing and writing the website

Anyone who is part of the IDeA Labs GitLab group should be able to modify the website. There are two ways to do so, described in following sections:

  1. Editing in your browser via Gitlab.com
  2. Running and editing the website locally on your computer

The website is written using a combination plaintext Markdown files and HTML files, with a number of extensions provided by Hugo. The theme was cobbled together by Sean Lane, and while Hugo is probably overkill for 90% of the website, the publications portion would be pretty difficult to reimplement eleswhere. It lost some minor bits of functionality of the old site that Nathan Woodbury created in PHP and MySQL, but now we don't have to worry about a PHP interpreter or hosting a DB.

Folder Structure

The idea with Hugo is that it separates the content in readable files and the layout as defined by a theme. As such, it expects to find specific things in specific places, so we'll briefly cover that here. The following is a description of the contents of each directory of the website repository. They are also explained further (along with some others not used here) at https://gohugo.io/getting-started/directory-structure/.

archetypes

Archetypes allow you to define a template ahead of time for a new piece of content. In our case, this could be a new visitor, a new piece of news, etc. They are not currently used.

assets

These should be static items that Hugo needs to preprocess. Mostly images that will be resized. Note that if you place an item here, but it is not referenced via it's Relative URL within the Hugo template, it will not be copied over to the generated website.

content

Where the meat of the website is located.

New lab member

  1. Create a new file similar to those found in content/people
  2. Add a corresponding image in assets/images/people

New visitor

  1. Create a new file similar to those found in content/visitors
  2. Add a corresponding image in assets/images/people/visitors
  3. If you want, you could fix it so there's an assets/images/visitors directory, but you'd need to go edit each of the visitor entries

New news article

  1. Create a new file similar to those found in content/news
  2. If applicable, add a corresponding image in assets/images/news

New project

  1. Create a new file similar to those found in content/projects
  2. If applicable, add a corresponding image in static/images/projects
  3. If applicable, add the publication file in static/publications

New publication

This part of the website borrows extremely heavily from https://github.com/jonathan-g/hugo-finisterre and it's sources. I tried to do the 20% of the work to get 80% of the functionality of the old website using these pieces, and it could likely use improvement.

  1. Create a new file similar to those found in content/publications
  2. If applicable, add the publication file in static/publications
  3. If applicable, add the publication file in static/presentations

Other content

The other content is expected to be more static and not changing as much. If you're making changes elsewhere, I'd recommend cloning this repo locally and doing the development with a local copy running, in order to have a good feel for how things work before pushing changes to the web server.

layouts

Where the structure of the web site via the template resides. Here be demons, try to develop locally before making changes.

static

Similar to assets, but basically just files you want to have copied over to the generated website and then served. If you really want to easily share a file with the world, you could just copy something here and push it.

Editing files in a web browser

Go to the project repo at https://gitlab.com/idealabs/website, login, navigate to the files you'd like to edit, and follow the instructions below.

Gitlab Web Editor

Local Installation

The second method is to clone the repo, and then edit the files locally as you would any project managed with Git:

  1. Download Hugo
  2. Clone the GitLab repository
  3. Run the web server (hugo serve)
  4. Modify the files
  5. Use Git to push the changes accordingly

Steps 1-2 only need to be done once, while the rest need to be done everytime you want to edit and run the website.

Download Hugo

Note that we're currently using Hugo 0.74.2 extended. Use other versions at your own discretion.

Clone the GitLab repository

1
2
$ cd /path/to/where/code/should/reside
$ git clone git@gitlab.com:idealabs/website.git
Tip: Checkout a new branch for large modifications

If you have a large change you want to make and track over time without pushing to the live production site, you can create a new branch. Once you're satisfied with the changes, you can then merge that branch with the master branch.

Assuming your current working directory is the wiki folder that you just clone, we can create a new branch:

1
$ git checkout -b name-of-my-branch

Further information can be found at the following links:

Run the webserver

Next, run the web server locally and see changes as you make them:

1
$ hugo serve

This opens a webserver (at http://127.0.0.1:1313 by default but it'll tell you otherwise) and watches the source files. If you make any changes, you can visit the website at that address in a web browser and see them as they change. After doing the steps above once, you only need to do this step and the following ones to edit the website in the future.

Modify the files

Open up your favorite text editor and modify the necessary files.

Use Git to push the changes accordingly

1
2
3
4
$ git add .                      # Add all files that you'd like to stage for your commit, change as needed
$ git commit -m "Changes dones"  # Commit the files staged by the previous step
$ git push origin master         # Do this the first time pushing
$ git push                       # Do this afterwards, to save on typing effort
Then go to the Merge Requests page, request a new merge with your changes, and review everything.

Note

You can cancel or modify a merge request if you realize you need to make more changes.