Конфигурация

Параметры темы

color_mode устанавливает только начальный режим. Посетители могут изменить его с помощью заголовка переключиться, и их выбор сохраняется в localStorage.

toc определяет, куда попадёт оглавление, построенное из заголовков страницы. auto кладёт его в правую колонку, если окну хватает ширины на третий столбец, и под заголовок страницы, если нет, — там он раскрывается по нажатию, а не стоит списком между заголовком и первым абзацем. expanded держит его в потоке и не пускает в колонку, collapsed превращает в раскрываемый блок, а hidden — или false — убирает совсем.

Иконки

Навигация по заголовку, управление цветовым режимом и кнопка возврата вверх используют встроенный SVG. из одного набора иконок. octicons — значение по умолчанию; выбрать значки Люцида с:

theme:
  name: primer
  icon: lucide

Оба набора включены в тему, поэтому ни один из вариантов не добавляет запрос CDN. Значок выбор применяется только к HTML-элементам управления темы. Выбор языка всегда использует глобус Octicon. Синтаксис значков Markdown и произвольные сторонние пакеты значков намеренно не поддерживаются.

Шрифты

Шрифты не являются обязательными: тема по умолчанию не запрашивает CDN шрифтов. Установите текст и кодируйте семейства независимо, затем укажите source на внешнюю таблицу стилей. или файл CSS в docs_dir:

theme:
  name: primer
  font:
    text: 'Inter, sans-serif'
    code: '"JetBrains Mono", monospace'
    source: https://fonts.googleapis.com/css2?family=Inter:wght@400;600&family=JetBrains+Mono&display=swap

Для самостоятельного сайта поместите файлы шрифтов и таблицу стилей в docs_dir, затем используйте относительный исходный путь:

theme:
  name: primer
  font:
    text: 'Atkinson Hyperlegible, sans-serif'
    code: 'Atkinson Hyperlegible Mono, monospace'
    source: fonts/fonts.css

@font-face {
  font-family: "Atkinson Hyperlegible";
  src: url("AtkinsonHyperlegible-Regular.woff2") format("woff2");
  font-display: swap;
}

Браузер обычно кэширует эти файлы. Самостоятельный хостинг позволяет избежать стороннего запросить и сохранить возможность использования сайта в автономном режиме после кэширования его ресурсов.

Макеты справа налево

Установите direction: rtl для документа с письмом справа налево. В теме ставится dir="rtl" в корневом элементе HTML и отражает его заголовок, боковую панель, мобильную навигацию, нумерация страниц, нижний колонтитул, меню и элементы управления с логическими свойствами CSS. Код и диаграммы намеренно остаются слева направо.

theme:
  name: primer
  direction: rtl

Направление — это настройка для всего сайта; тема не выводит это из страницы или языковая локаль.

!!! предупреждение «light_theme и dark_theme в настоящее время принимают только light и dark» Primer публикует четырнадцать тем (dark_dimmed, light_high_contrast, dark_tritanopia и т. д.), но в этой теме жетоны цвета поставляются только для двух их — полный набор добавит более мегабайта CSS. Именование любой другой темы отображает страницу вообще без цветов, а не с ошибкой. Поддержка большего количества тем отслеживается как будущее дополнение.

Привязки заголовков

Чтобы разместить привязку GitHub рядом с каждым заголовком, включите расширение toc с помощью ведущая постоянная ссылка, содержащая класс Primer anchor:

markdown_extensions:
  - toc:
      permalink: ""
      permalink_class: anchor
      permalink_leading: true
      permalink_title: Permanent link

Тема сама рисует октикон, поэтому для permalink задана пустая строка. чем обычный true. Это важно не только для внешнего вида: поисковый плагин MkDocs этого не делает. удалите глифы постоянных ссылок, чтобы в противном случае в результатах поиска отображался ¶.

Без этой конфигурации постоянная ссылка по-прежнему работает, она просто отображается как простой глиф. чем октикон.

Подсветка синтаксиса

Цвета кода берутся из переменных prettylights Primer, поэтому они следуют за активными. цветовой режим автоматически. Стиль No Pygments выбирать не нужно:

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences

Обе оболочки .highlight и .codehilite имеют стили, поэтому codehilite тоже работает.

Тема добавляет кнопку копирования в каждый блок Pygments .highlight. Он копирует видимый источник и сообщает, была ли операция буфера обмена успешной. Блоки визуализируемые плагинами, такими как Mermaid и Vega-Lite, намеренно исключены.

Элементы управления навигацией

После прокрутки на 400 пикселей в правом нижнем углу появляется кнопка возврата наверх. страницы. Он возвращает посетителя в начало документа и перемещает Фокус клавиатуры на ссылке в названии сайта. Движение происходит мгновенно, когда посетитель попросил уменьшить движение.

Расширения Markdown

Ничего из этого не требуется, но тема имеет стиль, который окупается только один раз. они на:

markdown_extensions:
  - admonition   # !!! note blocks, colored with Primer's alert palette
  - def_list
  - footnotes
  - tables
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tilde

admonition заслуживает внимания: расширение генерирует разметку и не использует CSS. сам по себе, и @primer/css не имеет для него никаких правил, поэтому нестилизованный увещевание – обычная неожиданность. Тема восполняет этот пробел — см. примеры.

Пользовательский CSS и JavaScript

extra_css загружается после каждой таблицы стилей, поставляемой в теме, поэтому ваши правила выигрывают. без необходимости !important:

extra_css:
  - css/overrides.css
extra_javascript:
  - js/site.js
  # MkDocs 1.5+ also takes the mapping form.
  - path: js/chart.js
    type: module

Styling рассказывает, что в неё писать: собственные переменные раскладки темы и почему переопределение цветового токена Primer в :root отбрасывается, а то же правило под двумя селекторами атрибутов срабатывает.

extra_javascript генерируется в конце <body>, после собственного имени темы. сценарии.

!!! обратите внимание: «Плагины, которые внедряют свои собственные ресурсы» Плагин, который записывает теги <link> в HTML страницы, а не добавляет их в extra_css — mkdocs-glightbox — один из них — появляется после ваших переопределений. Стиль те, у кого более конкретный селектор, а не полагающиеся на порядок.

Редактировать ссылки

Нижний колонтитул ссылается на исходный файл, если установлены repo_url и edit_uri:

repo_url: https://github.com/you/your-project
edit_uri: edit/main/docs/