6  Создание веб-страниц

Веб-сайт — это набор HTML-страниц, имеющих общие элементы, связанные общей навигацией и стилями. По сути, веб-сайт является одним из основных форматов Quarto документов для представления результатов. Это может быть как простая веб-страница, так и более сложный документ: веб-книга, Quarto Manuscript, дэшборд, блог или презентация. Примеры веб-страниц, созданных с помощью Quarto, можно посмотреть в Галерее Quarto.

6.1 Создание минимальной веб-страницы

Кратко перечислим несколько способов для создания веб-страниц: в Visual Studio Code (или Positron), RStudio и с помощью командной строки, как это было описано в параграфе Работа с проектами.

Для создания простейшего документа Quarto в Visual Studio Code (соответственно, Positron) нужно выбрать в меню File : New File… : Quarto Document.

Рисунок 6.1: Пример создания веб-страницы в Quarto в Visual Studio Code / Positron

Для создания веб-страницы в Quarto в RStudio достаточно последовательно выбрать в меню File : New File : Quarto document…, либо как на рисунке ниже.

Рисунок 6.2: Пример создания веб-страницы в Quarto в RStudio

Для того, чтобы создать проект в Quarto с помощью терминала, можно перейти в директорию, где будет создан проект и далее следовать указаниям, набрав команду quarto create project либо quarto create-project --type website.

Terminal
quarto create project
Рисунок 6.3: Пример создания веб-страницы в Quarto в терминале

В процессе создания необходимо указать название директории и проекта, что потом возможно изменить.

Рисунок 6.4: Процесс создания веб-страницы в Quarto в терминале

Для предварительного просмотра необходимо набрать команду quarto preview, а для полного рендеринга проекта — команду quarto render.

Пример структуры созданного веб-сайта как проекта в новой директории:

my_directory/my_title 
1├── _quarto.yml
2├── index.qmd
3├── about.qmd
4└── styles.css
1
Файл с метаданными проекта Quarto (_quarto.yml).
2
Домашняя страница проекта (index.qmd).
3
Страница «О проекте» (about.qmd).
4
Стилевые файлы (styles.css).

В случае, если веб-страница создается в RStudio или Visual Studio Code, будет создан небольшой документ на основе шаблона, который будет содержать:

---
title: "Заголовок"
format: html
---

Материал веб-страницы...

Если веб-страница была создана в рамках проекта, то _quarto.yml будет содержать:

_quarto.yml
project:
  type: website

В этом случае при рендеринге проекта Quarto создается каталог _site, который в дальнейшем будет публиковаться и содержит основной файл index.html, а также другие необходимые ресурсы. Напомним, что рендер в IDE (Visual Studio Code, Positron, RStudio) осуществляется в случае одностраничного документа для файла index.qmd, а полный рендер проекта — с помощью команды quarto render в терминале.

6.2 Структура веб-сайта

В данном разделе рассматривается преобразование проекта Quarto в веб-страницу, организация ссылок на другие страницы, а также возможности включения и исключения файлов при создании веб-страницы.

6.2.1 Локализация

При создании документа Quarto имеет смысл сразу определить основной язык документа с помощью языковых тегов в соответствии со стандартом BCP 47 через параметр lang, например, достаточно указать в метаданных yml значение lang: ru для русского языка.

Quarto_eng
---
title: "Title"
author: Andrew Smith
date: today
---

This is a Quarto website.
Quarto_ru
---
title: "Заголовок"
author: Андрей Кузнецов
date: today
lang: ru # <-- определение языка
---

Это веб-сайт Quarto.

Существуют случаи, когда есть необходимость изменить перевод терминов. Переопределить термины можно с помощью параметра language, для этого необходимо указать новое значения термина, указанного в файле перевода. Всевозможные встроенные переводы можно посмотреть в каталоге language, например, русский перевод хранится в файле _language-ru.yml.

_quarto.yml
title: "Исходный вариант"
author: 
  name: Андрей Кузнецов
  affiliation: "Федеральный университет"
date: today
lang: ru
_quarto.yml
title: "Переопределение терминов"
author: 
  name: Андрей Кузнецов
  affiliation: "Федеральный университет"
date: today
lang: ru
language: # <-- переопределение терминов
  title-block-affiliation-single: "Организация"
  title-block-published: "Дата"

6.2.2 Как документ Quarto будет преобразован в страницу URL

Покажем, каким образом содержимое проекта Quarto согласуется с тем, что будет находиться в каталоге _site (или его эквиваленте, например, _book), который будет затем публиковаться. Путь {domain} — это основной домен для представления базового URL нашего веб-сайта.

Таблица 6.1: Примеры заполнителя {domain}
Пример заполнителя {domain} Интерпретация
http://localhost:5555 локальный просмотр
https://username.github.io/repository_name проект на GitHub Pages
https://username.quarto.pub/project-name проект на Quarto Pub
https://your-address.netlify.app проект на Netlify

Ниже приведем пример преобразования ссылок в URL адреса (справа) после рендеринга в общей структуре проекта, определяемого с помощью _quarto.yml. Обратите внимание на то, как будут интерпретироваться файлы index.qmd, которые становятся целевой страницей для каталога, который содержит index.qmd.

your-website/  
├── _quarto.yml
├── index.qmd             {domain}
├── about.qmd             {domain}/about.html         
├── posts/                       
|    ├── index.qmd        {domain}/posts            
|    └── latest-post.qmd  {domain}/reports/latest-post.html                        
└── data/                         
    └── database.parquet  {domain}/data/database.parquet

6.2.4 Включение и исключение контента

В Quarto существует возможность явного указания того, что необходимо включить в рендер проекта.

_quarto.yml
project:
  type: website
  render: 
    - includes.qmd

Аналогично, возможно исключить контент при рендеринге, явно указав это с помощью !.

_quarto.yml
project:
  type: website
  render: 
    - "*.qmd"
    - "!ignore-dir/"
    - "!ignore-doc.qmd"

Важно отметить, что в том случае, если в проект необходимо включить файл (например, с данными), который затем будет находиться в папке _site, то лучше всего указать это в настройках проекта.

_quarto.yml
project:
  type: website
  resources: 
    - "*.parquet"
Предупреждение

Все ссылки на файлы в Quarto из других элементов проекта должны быть указаны относительно корневого каталога проекта, в котором содержится index.qmd и _quarto.yml. Например, ссылка на файл ../../file.ext означает что файл находится на два уровня выше относительно корневой директории проекта.

Кроме того, в качестве ресурсов, указываемых в параметре resources, могут выступать файлы, которые копируются в выходной каталог _site (или аналогичный):

  • 404.html — Страница «Ошибка 404», на которую происходит переход, когда страница была перемещена или удалена, не совпадает имя файла в коде и на сервере, и т. п.,
  • _redirects, используемый некоторыми провайдерами ля обеспечения перенаправления страниц, например Netlify
  • .nojekyll, файл, используемый страницами GitHub для обхода сборки с помощью Jekyll, например, при публикации на GitHub Pages.

Если необходимо добавить иной контент в ваш документ, например, из файла JavaScript, CSS или HTML, это можно сделать с помощью опций, начинающихся с include-in-*. Например, таким образом можно включить данные, собираемые с помощью системы аналитики Яндекс Метрика и т. д.

Таблица 6.3: Список опций для включения содержимого файла в Quarto документ
Вариант включения Описание
include-in-header Включение содержимого файла в конец заголовка. Это может быть использовано, например, для включения специального CSS или JavaScript в HTML-документ
include-before-body Включение содержимого файла в начало тела документа (например, после тега <body> в HTML). Это можно использовать для включения панелей навигации или баннеров в HTML-документы
include-after-body Включение содержимого файла в конец текста документа (перед тегом </body> в HTML)

Вы можете указать один файл или несколько файлов для каждого из этих параметров напрямую или использовать явно ключ file:. Чтобы включить дословно содержимое в заголовок YAML, используйте подключ text.

При использовании text: можно добавить | чтобы указать, что значение представляет собой многострочную строку. Ниже показан пример такого рода включения.

format:
  html:
    include-in-header:
      - text: |
          <script src="https://examples.org/demo.js"></script>
      - file: analytics.html
      - comments.html
    include-before-body: header.html

Отметим, что параметры рендеринга, которые должны применяться ко всем элементам проекта, для каждого из форматов должны быть перечислены в параметрах format.

_quarto.yml
format:
  html:
    theme: cosmo
  pdf: default

Заключение