This repository contains the code to host the Whitaker Lab website: https://whitakerlab.github.io. It is powered by Hugo and uses the Minimo Theme.
Continuous integration is managed by GitHub Actions. If our build status badge (at the top of this page) is not a beautiful bright green, please take a look and see if you can fix any of the problems!
I (Kirstie) find myself googling for the following commands everytime I interact with this repository, so here they are to make my life easier!
hugo server -D
To create a new blog post you can either:
hugo new blog/title-of-blog.md
template.md
file under the content/blog
folder.All blog posts must contain the following information at the top of the Markdown document.
---
title: "Template" # Update with title
date: 2021-05-19T00:00:00+00:00 # Update with date. You can leave the time as 0's if unsure.
draft: true # Change to false
authors: [] # Comma separated list of authors surrounded by double quotes. E.g. ["kirstiewhitaker", "janedoe"]
categories: blog # DO NOT CHANGE
tags: [] # List of tags
---
The content of the blog can then be written, in Markdown syntax, under the second ---
divider.
We recommend naming blog files with the following convention:
YYYY-MM-DD-title-of-blog-post.md
This means the directory will be ordered by date the post was added (ascending) and will avoid name clashes with repeating blogs, such as lab-meeting.md
.
Please add any images you wish to include to the static/images
folder.
They are then referenced as /images/image-name
, without the static
prefix.
If you are uploading a lot of images for a single post, you may wish to create a dedicated subdirectory under static/images
.
Hugo uses shortcodes to embed external content into pages without the need to copy long lines of HTML code. However, if a shortcode doesn't exist for the content you'd like to embed, copying the long HTML code will still work!
Some useful shortcode examples:
{{< tweet TWEET_ID >}}
where TWEET_ID
is the numeric part of the Tweet URL.
Docs
{{< figure src="https://github.com/WhitakerLab/whitakerlab.github.io/raw/master/" alt="" caption="" >}}
where src
could be a URL or a reference to a local image (that is, /images/image-name
), alt
defines the alt-text, and caption
renders an image caption.
Any Markdown contained in caption
will be rendered as expected.
Docs
{{< youtube VIDEO_ID >}}
where VIDEO_ID
is the code that follows v=
in the URL.
Docs
The shortcodes ref
and relref
will look up pages by their relative path (e.g., blog/post.md
) or their logical name (post.md
) and return the permalink (ref
) or relative permalink (relref
) for the found page.
ref
and relref
also make it possible to make fragmentary links that work for the header links generated by Hugo.
See the documentation for examples.
Create a new TOML file under the data/authors
folder.
janedoe.toml
templateauthor.toml
as an exampleAdd your data. Each file must follow the below structure.
social.twitter
field is optionalid = "" # Must be the same as the filename e.g. templateauthor
[email]
username = "" # This is the part of your email BEFORE the @
host = "" # This is the part of your email AFTER the @
[name]
display = "" # How you would like your name to be displayed
[social]
twitter = "" # Your Twitter handle (no @)
Jane Doe's example would look like this.
id = "janedoe"
[email]
username = "janedoe"
host = "gmail.com"
[name]
display = "Jane Doe"
[social]
twitter = "JaneDoe"
You can now be listed as an author for posts in the authors
field of the post's front matter like so.
authors: ["janedoe"]
Clone the repo and change into the directory
git clone https://github.com/WhitakerLab/whitakerlab.github.io.git
cd whitakerlab.github.io
Update the theme in the themes
directory
cd themes/minimo
git checkout master
git fetch && git pull
cd ../..
Check our config.toml
is up-to-date with the latest config.toml
format.
It's also a good idea to double check the configuration settings of Minimo.
Lastly, check Hugo can still build the site.
hugo server -D
Add, commit and push the updated theme.
git add themes/minimo
git commit -m "Update [theme]: minimo"
git push