Участие в документации Kubernetes

Edit This Page

Организация контента

Этот сайт использует Hugo. В Hugo организация контента — основная концепция.

Заметка: Подсказка: при редактировании контента используйте команду hugo server --navigateToChanged, чтобы запустить Hugo.

Списки страниц

Порядок страницы

Меню в сайдбаре, каталог страниц документации используют стандартный порядок перечисления Hugo, который сортирует элементы по весу (от 1), дате (начиная с самых новых) и затем по заголовку ссылки.

Таким образом, если вам нужно поднять страницу или раздел, определите её вес в фронтальной части:

title: Моя страница
weight: 10
Заметка: Для значений веса страниц лучше не использовать привычный порядок 1, 2, 3…, а предпочесть другой интервал, например, 10, 20, 30… В будущем это позволит вставить последующие страницы в желаемую позицию.

Главное меню документации

Главное меню Документация состоит из разделов по пути docs/ с установленным флагом main_menu в фронтальной части файла раздела _index.md:

main_menu: true

Обратите внимание, что текст ссылки берётся из переменной linkTitle, поэтому, если вы хотите, чтобы он отличался от заголовка страницы, измените его в файле:

main_menu: true
title: Название страницы
linkTitle: Название, которое будет использоваться в ссылках
Заметка: Перечисленные выше переменные должны быть определены для каждого перевода. Если вы не видите созданный вами раздел в меню, скорее всего, это может быть связано с тем, что Hugo не определил его как раздел. Создайте файл _index.md в директории раздела.

Документация в боковом меню

Меню сайдбара в документации собирается из текущего дерева разделов по пути docs/.

Оно отобразит все разделы и их страницы.

Если вы хотите, чтобы раздел или страница не отображались в меню, установите для флага toc_hide значение true в фронтальной части файла:

toc_hide: true

При переходе к непустому разделу будет отображаться указанный раздел или страница (например, _index.md). В противном случае выводиться первая страница в этом разделе.

Каталог документации

Каталог страниц на главной странице документации сгенерирован с учётом всех разделов и страниц документации.

Если вы хотите скрыть раздел или страницу, установите для флага toc_hide значение true в фронтальной части файла:

toc_hide: true

Главное меню

Ссылки сайта в верхнем правом меню, а также в футере, создаются посредством сканирования страниц. Этот процесс гарантирует, что страница действительно существует на сайте. Поэтому, если раздела case-studies на сайте (или в переводе) не существует, ссылка не появится.

Пакеты страниц

В дополнение к отдельным страницам с контентом (Markdown-файлам), Hugo поддерживает пакеты страниц (page bundles).

К примеру, пользовательские макрокоды Hugo — узел пакета (leaf bundle). Все, что находится в директории, включая index.md, будет частью пакета. Сюда также относятся относительные ссылки на страницы, изображения, которые могут быть обработаны и т.д.:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Другой распространённый пример — это пакет includes. Он устанавливает переменную headless: true, которая означает, что файл не будет доступен по собственному URL-адресу. Вместо этого он будет использоваться в других страницах как вставляемый файл.

en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Необходимо отметить следующие особенности файлов в пакетах:

  • Для переведенных пакетов любые отсутствующие файлы будут унаследованы от файлов на оригинальном (английском) языке. Это позволяет избежать дублирования.
  • Все файлы в пакете — в Hugo называются ресурсы (Resources), в которых вы можете определить метаданные, зависимые от языка, например, параметры и заголовок, даже если они не поддерживают в фронтальной части (YAML-файлы и т.д.). Смотрите Метаданные ресурсов страницы для получения дополнительной информации.
  • Значение, которое вы получаете через .RelPermalink в Resource будет отличаться в зависимости от страницы. Смотрите Постоянные ссылки для получения дополнительной информации.

Стилизация

Исходные файлы стилей в формате SASS находятся в директории assets/sass и автоматически собираются Hugo.

Что дальше

Обратная связь