OSUOSL Hugo Static Site

Migrated from our static Pelican site

Based off of the Mainroad theme and the previous OSL theme

Development

Prerequisites

Read the Hugo getting started guide's prerequisite list and install the Hugo binary or package. You can check if it is installed from the command line by running:

hugo version

This project uses npm for the functionality of Prettier and Markdownlint. You can check that npm is installed from the command line by running:

npm -v

The search feature is implemented using Pagefind and can be run with the npm script serve or by downloading the binary.

Setup

If you do not have permissions to work directly on a branch of the repository, you will have to fork the repo and work from your fork. If you do have permission, create a branch and work from your branch.

Once the prerequisites are installed and you are working off the fork or branch, clone the repository to your local machine.

This can be done from the command line:

# Fork
git clone [email protected]:YOURUSERNAMEHERE/website.git ./osl-website

# Branch
git clone [email protected]:osuosl/website.git ./osl-website

Then, navigate to the folder and then install the dependencies:

cd ./osl-website
npm install

Local Development

To compile and host the site under development on port 1313, run:

hugo server

Once Hugo is done setting up, you should see a success message:

Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Formatting and Linting

This project uses prettier and markdownlint. You can install them in your preferred editor to see changes as you edit or run them from the command line.

To format and lint from the command line, run:

# Format via prettier
npm run format

# Lint via markdownlint
npm run lint

Preview Production

If you want to preview the production server to see the full search functionality, you can build the pages and then serve from Pagefind. Pagefind sources from the public/ directory Hugo compiles when the website is built.

First compile the pages:

hugo

Then run it using Pagefind through the provided helper npm script or the binary using the specific flags:

# NPM helper script
npm run serve

# Binary
./pagefind --site public --serve

Adding Content

Content is added inside the /content folder, though it varies based on what you would like to do.

Adding a New Blog Post

Regular pages use the default /archetypes/default.md archetype.

Blog posts are stored in /content/blog and use the associated /archetypes/blog.md archetype.

To add a blog post, use the hugo new command:

hugo new blog/your-slug-title-here.md

The author of a page should be included as an array of authors within the front matter:

---
# ...
authors: [OSUOSL Admin]
# ...
---

To add a header image at the top of a blog post, use the CSS tag #blog:

![Image Alt](/images/image_path#blog)

Adding a New Tag

Tags (called Terms in Hugo) are added simply by adding an associated string in the frontmatter of a blog post. This alone will create a semi-broken tag due to how tags are rendered, so you will have to add an associated page in the content folder to add metadata.

After you add a tag to a blog post, create a new file in the directory /content/tags/[tag name here]/_index.md, making the folder if it does not already exist.

Inside this file, include the frontmatter template below as well as any content you want displayed along with the tag:

---
title: "Example Tag Here"
slug: example-tag-here
---

Content here will be placed on the tag page. You may also include images here.

If you do not do this, the tag will be displayed as not having a name.

License

Apache 2.0