Это один из постов о советах и трюках, которые я использовал при настройке блога на Hugo.

Я хотел создать страницу 404. Конечно, я загуглил что-то вроде "404 page hugo" и конечно же попал на официальную документацию.

Официальная документация Hugo по этой теме довольно бедна в плане деталей.

У меня есть статический сайт, который хостится на Nginx, запущенном внутри Docker-контейнера.

Итак, есть 3 шага для реализации этой идеи.

Во-первых, нам нужно создать саму страницу, используя HTML-шаблонизатор Hugo. Затем нужно настроить сервер (Nginx), чтобы использовать эту страницу в случае ошибки 404. В качестве бонуса, хотя для меня это обязательно, мне нужно поместить настроенный сервер внутрь Docker-образа, который загружается в registry.

Hugo

Давайте посмотрим, что говорит документация. Создайте шаблон 404.html внутри layout/404.html

{{ define "main"}}
    <main id="main">
      <div>
       <h1 id="title"><a href="{{ "/" | relURL }}">Go Home</a></h1>
      </div>
    </main>
{{ end }}

Вы можете использовать любую разметку, которую хотите. Это полностью поддерживает шаблонизатор, который вы используете для любого шаблона Hugo.

Более того, вы можете делегировать создание layouts/404.html вашей кастомной теме, как сделал я. Таким образом ваш конкретный блог будет чистым от подобных layouts.

Nginx

В документации есть часть Automatic Loading. Здесь можно увидеть общий подход для некоторых известных серверов.

Nginx. You might specify error_page 404 /404.html; in your nginx.conf file.

Где находится этот конфиг и как его обновить?

По умолчанию Nginx использует конфиг, который находится здесь: /etc/nginx/conf.d/default.conf. Я просто взял его дефолтную версию и немного изменил вот так:

server {
    listen       80;
    listen  [::]:80;
    server_name  localhost;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }

    error_page 404 /404.html; # Здесь и ниже — обработка ошибки 404, которую пыталась описать документация
    location = /404.html {
        root   /usr/share/nginx/html;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }

}

Docker

Теперь мы знаем, что нужно изменить конфиг Nginx. Nginx запускается в Docker-контейнере для нашего Docker-образа. У меня есть Dockerfile в корне проекта Hugo, это конфиг, который используется для создания Docker-образа. Скопируйте и вставьте конфиг Nginx из предыдущего шага в ту же директорию, что и Dockerfile. Я назвал его nginx.conf. Затем обновите Dockerfile вот так:

FROM nginx:alpine
COPY ./public /usr/share/nginx/html

# Буквально скопировать файл nginx.conf из директории Dockerfile в /etc/nginx/conf.d/default.conf контейнера
COPY ./nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

Результат

Вы можете увидеть "демо" на этом сайте. Просто введите любой невалидный URL в адресную строку, и вы увидите содержимое моей страницы 404.

Для более специфичных деталей вы можете посмотреть мой предыдущий пост о полном pipeline для деплоя блога, который я настроил.