Redirects

Context

Previously, Chainguard Academy used two kinds of redirects.

• Meta refresh redirects (created by Hugo aliases)
• 301 redirects (created as rewrite rules in nginx)

In general, 301 redirects are preferred for SEO. The main reason for this is that some spam websites use meta refreshes in conjunction with dark patterns, taking advantage of the fact that a dummy page loads first. However, 301s are a more heavyweight approach and we should be slower to create these kinds of redirects as we go forward.

We've created some infrastructure on edu that replicates all Hugo aliases (aliases in front matter) as 301 redirects. Below are some guidelines for creating these aliases as we move forward.

Creating a Redirect

Currently, there are two ways of creating a redirect:

1. Add an alias to frontmatter in Hugo. This will automatically generate a 301 redirect in our nginx configuration.
2. Create a rule directly in our nginx configuration.

Say there is a historical page, https://edu.chainguard.dev/administration/updates, and we want to move it permanently to the https://edu.chainguard.dev/images/updates path on edu. We would move that page to the correct folder, then create an alias pointing to the previous URL.

Creating rules directly in the nginx configuration can be done in situations where there is no destination page on edu, such as if we need to redirect to an external resource

Guidelines for Using 301 Redirects

1. Ask yourself: do we need a redirect? If you're creating an article for the first time, there is likely no reason to include an alias / redirect. Only create a 301 redirect if a resource has moved from one URL to another. We all copy front matter, but don't include the alias section by default when creating a new article.
2. For historical reasons, some pages include aliases in the front matter that direct to the current location of the page. There is logic to ignore these situations in our infrastructure, but this type of alias is redundant and not needed.
3. Be mindful to only use legal URL characters in your aliases. There should not be spaces, semicolons (;), or question marks. If these characters are included, they may lead to a nonfunctional build or cause the redirect to be nonfunctional.
4. Do not redirect from an existing category page. This will cause all articles in that category to be improperly redirected. The only circumstance where a category-level redirect should be created is if a category is deleted or renamed. Aliases on category pages should probably be avoided in general.
5. Bear in mind that moving pages creates a kind of technical debt that we have to carry with us moving forward. Reorganizations will be needed but we should put effort into the redirect strategy going in. Remember that most pages are accessed from Google or other external links and not from the site navigation.

• Don't redirect to an irrelevant page. If we delete an article permanently, we should either redirect to an article with a useful connection to the topic or leave the page as a 404. Don't redirect to home.

The important takeaway is that creating a Hugo alias now creates a redirect that Google's crawler and user browsers take seriously as a signal that the page has moved. Create redirects sparingly and with consideration.