Шорткоды
Шорткоды - это простые фрагменты внутри файлов контента, вызывающие встроенные или пользовательские шаблоны.
Некоторые встроенные шорткоды:
- highlight - этот шорткод преобразует предоставленный исходный код в HTML с подсветкой синтаксиса.
- youtube - шорткод включает адаптивный видеоплеер для видео на YouTube.
Встроенные шорткоды Hugo охватывают многие распространенные, но не все варианты использования. Также Hugo предоставляет возможность легко создавать собственные шорткоды для удовлетворения потребностей сайта.
Создадим HTML-шаблон в каталоге themes/mytheme/layouts/shortcodes. Вызывать шорткод themes/mytheme/layouts/shortcodes/bs-img.html будем {{< bs-img />}} или {{% bs-img /%}} в зависимости от типа выбранных параметров. Можно организовать свои шорткоды в подпапках, например, в layouts/shortcodes/boxes. Затем эти шорткоды будут доступны по их относительному пути, например:
{{< boxes/square >}}Порядок поиска шаблона шорткода:
- /layouts/shortcodes/<SHORTCODE>.html
- /themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html
Создавая шорткоды, можно использовать позиционные или именованные параметры.
В шорткодах с позиционными параметрами важен порядок параметров. Если шорткод имеет одно обязательное значение, позиционные параметры работают очень хорошо и требуют меньше ввода от авторов контента.
Для более сложных макетов с несколькими или необязательными параметрами лучше всего подходят именованные параметры. Несмотря на то, что именованные параметры менее кратки, они требуют меньшего запоминания от автора контента и могут быть добавлены в объявление шорткода в любом порядке.
Доступ ко всем параметрам шорткода можно получить через .Get метод.
Чтобы получить доступ к параметру по имени, используем .Get метод, за которым следует именованный параметр в виде строки в кавычках:
{{ .Get "name" }}Чтобы получить доступ к параметру по позиции, используем .Get числовую позицию, за которой следует числовая позиция, помня, что позиционные параметры имеют нулевой индекс:
{{ .Get 0 }}Изображения
Шорткод для вывода адаптивного изображения через bootstrap используем позиционные параметры bs-img.html:
{{ $imagename := (.Get 0) }}
{{ $alt := .Get 1 }}
<img class="img-fluid" src="{{ $imagename }}" alt="{{ $alt }}">Вызов
{{< bs-img "/images/acid.png" "Кислота" >}}Более интересный вывод изображений можно получить с помощью библиотеки Lightbox.
npm install lightbox2Копируем файлы lightbox.min.css и lightbox-plus-jquery.min.js из node_modules/lightbox2/dist/ в папку темы themes/mytheme/static. Добавляем строки в themes/mytheme/layouts/partials/head.html
<link rel="stylesheet" type="text/css" href="{{ .Site.BaseURL }}css/lightbox.min.css" />и в themes/mytheme/layouts/partials/script.html
<script src="{{ .Site.BaseURL }}js/lightbox-plus-jquery.min.js"></script>Создадим шорткод с именованными параметрами. Первым обязательным параметром src - будет полное имя файла изображения. Второй необязательный параметр будет title, для показа заголовка, а также alt атрибута изображения. И третьим атрибутом будет название группы lg - для группы связанных изображений, которые объединим в набор. Вызов шорткода будет таким:
{{< lb-img src="/images/screen.png" title="Screen" lg="Album" >}}Создадим такой файл themes/mytheme/layouts/shortcodes/lb-img.html:
{{ $src := "" }}
{{ with .Get "src" }}{{ $src = . }}{{ else }}{{ errorf "missing value for param 'src': %s" .Position }}{{ end }}
{{ $title := "" }}
{{ with .Get "title" }}{{ $title = . }}{{ end }}
{{ $lg := delimit (shuffle (seq 1 9)) "" }}
{{ with .Get "lg" }}{{ $lg = . }}{{ end }}
<a href="{{ $src }}" data-lightbox="{{ $lg }}" data-title="{{ $title }}" data-alt="{{ $title }}">
<img src="{{ $src }}" class="img-fluid" alt="{{ $title }}">
</a>Проверяем наличие обязательного параметра - имя файла изображения. С помощью строки:
{{ $lg := delimit (shuffle (seq 1 9)) "" }}Задаем случайное значение параметра data-lightbox. Для создания группы изображений следует при вызове шорткода указывать одинаковый параметр lg.
Видео
Теперь добавим ещё один шорткод для вывода видео с Youtube - bs-video.html.
{{ $id := "" }}
{{ with .Get "id" }}{{ $id = . }}{{ else }}{{ errorf "missing value for param 'id': %s" .Position }}{{ end }}
{{ $title := "" }}
{{ with .Get "title" }}{{ $title = . }}{{ end }}
<div class="ratio ratio-16x9">
<iframe src="https://www.youtube.com/embed/{{ $id }}?rel=0" title="{{ $title }}" allowfullscreen></iframe>
</div>Вызов шорткода с обязательным параметром - id.
{{< bs-video id="Nzq9epS2b1A" >}}Таблицы
Часто на страницу необходимо вывести таблицу с определенными данными. Для хранения таких данных существует каталог Data. В этой папке должны храниться дополнительные данные, которые Hugo может использовать при создании сайта.
Файлы данных не предназначены для создания отдельных страниц. Они должны дополнять файлы контента. Эти файлы должны быть в формате YAML, JSON, XML или TOML (с использованием расширения .yml, .yaml, .json, .xml или .toml). Но мне удобнее получать файлы с таблицами конвертируя их в формат CSV. В большинстве офисных программ для работы с таблицами, таких как LibreOffice Calc, существует возможность сохранить таблицу в CSV файл. Но для загрузки локальных файлов с помощью getJSON и getCSV исходные файлы должны находиться в рабочем каталоге Hugo.
Локальные CSV-файлы, которые необходимо загрузить с помощью функции getCSV должны находиться вне каталога data.
Для этого в корне проекта создадим папку CSV, в нее будем сохранять файлы с данными для таблиц.
Создадим файл шорткода:
{{ $file := .Get 0 }}
{{ $col := .Get 1 }}
<div class="table-responsive">
<table class="table table-sm table-hover">
{{ range $i, $r := getCSV "," $file }}
{{ if eq 0 ($i) }}
<thead class="table-light">
<tr>
{{ range $index, $num := (seq $col) }}
<th>{{ index $r $index }}</th>
{{ end }}
</tr>
</thead>
{{ else }}
<tr>
{{ range $index, $num := (seq $col) }}
<td>{{ index $r $index }}</td>
{{ end }}
</tr>
{{ end }}
{{ end }}
</table>
</div>Вызов шорткода производим с двумя параметрами:
{{< csv-table "csv/street.csv" 3 >}}Первым параметром является путь до CSV файла, второй параметр указывает какое количество столбцов выводить из таблицы. Так же обязательным является наличие в первой строке CSV файла сохранять заголовки столбцов.
Hooks
Хуки позволяют переопределять функциональность рендеринга Markdown.
Можно переопределить определенные части рендеринга Markdown по умолчанию в HTML, создав шаблоны с базовыми именами render-{kind} в layouts/_default/_markup.
Добавим в файл themes/mytheme/layouts/_default/_markup/render-link.html.
<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
Теперь ссылки будут открываться в новом окне. Можно не создавать шорткод bs-img.html, а переопределть в файле themes/mytheme/layouts/_default/_markup/render-image.html метод оформления изображений.
<img src="{{ .Destination | safeURL }}" class="img-fluid" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />Итоги
Хотелось написать подробный обзор HUGO, не получилось. Немного рассмотрел создание сайта, темы. Многое ещё не разобрал.
Плюсы
- Хорошая документация, но и в ней бывают пробелы.
- Быстрая генерация страниц.
- Установка из одного бинарника.
- Можно работать исключительно в консоли.
- Нетребовательный к хостингу.
Минусы
- Долгая настройка темы под себя.
- Необходимы знания HTML, CSS и т.д.
- GO немного мутный язык (для меня)
Мнение
Для кого этот генератор? Больше всего подходит для создания сайтов с документацией, мини-блогов.
Список статей:
