rss_feedHamel Husain ·15.07.2025 open_in_newОригинал

Syntax Highlighting – Hamel’s Blog - Hamel Husain

#Developer Tools #Technical Documentation

auto_awesomeКраткое саммари

Заметка Hamel Husain объясняет, как работает подсветка синтаксиса в Quarto, которая опирается на механизм подсветки pandoc. Разбираются две ключевые концепции: цветовые темы синтаксиса (настраиваются через параметр highlight-style, с возможностью задать отдельные темы для светлого и тёмного режимов) и определения синтаксиса (правила подсветки в XML-файлах по схеме KDE/Kate). По умолчанию Quarto использует тему arrow-light, а любимая тема автора — dracula. Чтобы задокументировать язык, не поддерживаемый из коробки, можно добавить собственное определение синтаксиса через параметр syntax-definitions. В качестве примера показано, как создать вымышленный язык Fomo — почти идентичный Python, но с ключевым словом fomo для определения функций — скопировав python.xml, изменив поля name, style и extension и добавив fomo в список defs.

translate EN + RU EN RU

Предыстория

Подсветка синтаксиса в Quarto работает так же, как pandoc обрабатывает подсветку синтаксиса. Есть две важные концепции, касающиеся подсветки синтаксиса:

1. Цветовые темы синтаксиса

Цветовые темы синтаксиса позволяют настроить цвета, отображаемые при подсветке синтаксиса. Они задаются с помощью настройки highlight-style. Цветовую тему синтаксиса можно изменить либо во front matter, либо для всего сайта в _quarto.yml, вот так:

Front Matter _quarto.yml

--- highlight-style: custom.theme ---

Если у вас есть и светлая, и тёмная темы, скорее всего вы захотите задать их по отдельности, вот так:

--- highlight-style: light: custom-light.theme dark: custom-dark.theme ---

_quarto.yml

format: html: theme: light: assets/ek-theme-light.scss dark: assets/ek-theme-dark.scss highlight-style: light: assets/ek-light.theme dark: assets/ek-dark.theme

Эти цветовые темы задаются файлами json по схеме, описанной здесь. Однако рекомендуется выбрать одну из тем, которые Quarto уже предоставляет, и отредактировать её. По умолчанию Quarto использует тему arrow-light. Это означает, что если вас устраивает то, как Quarto подсвечивает синтаксис, вы можете просто немного подправить эту тему. Лично моя любимая тема — dracula. Полезно просмотреть эти разные темы, чтобы получить представление о том, что именно можно менять.

2. Определения синтаксиса

Определения синтаксиса задают правила, по которым подсвечивается синтаксис. Правило — это строка, символ или регулярное выражение, с которым сопоставляется анализируемый текст. Это полезно, если вам нужно задокументировать язык, который не поддерживается Quarto из коробки. Посмотреть список поддерживаемых языков можно этой командой:

quarto pandoc --list-highlight-languages

Определения синтаксиса задаются в файлах xml, которые следуют этой схеме. Примеры определений синтаксиса для различных языков можно найти здесь.

У Quarto есть дополнительные примеры определений синтаксиса здесь, на которые полезно взглянуть. Обратите внимание, как в XML-файле задаются название языка и его расширения файлов.

Чтобы добавить дополнительное определение синтаксиса или переопределить существующее, задайте параметр syntax-definitions в вашем файле _quarto.yml, вот так:

_quarto.yml

format: html: syntax-definitions: - new_language.xml

Пример определения нового языка показан ниже.

Пример

Предположим, у вас есть новый язык программирования под названием Fomo, который точно такой же, как Python, за исключением того, что функции можно определять с помощью fomo в дополнение к def. Например, рассмотрим этот код на Python:

def hello_world(): "An example" pass

К сожалению, если попытаться использовать ограждение кода Python для Fomo, это выглядит так:

fomo hello_world(): "An example" pass

Поскольку Fomo почти идентичен Python, можно начать с копирования определения синтаксиса python в файл с именем fomo.xml и редактирования полей языка name, style и extension, вот так:

fomo.xml

- +


                      
                                            Также нужно добавить fomo в список defs, вот так:
                          
                      
                                            fomo.xml
                          
                      
                                               class  def + fomo  del  global  lambda  nonlocal  
                          
                      
                                            После этого можно добавить определение синтаксиса Fomo в ваш проект Quarto с помощью параметра syntax-definitions, вот так:
                          
                      
                                            _quarto.yml
                          
                      
                                            format:  html:  syntax-definitions:  - fomo.xml
                          
                      
                                            В данном случае fomo.xml находится в корне проекта Quarto, но вы можете поместить его и в подпапку.
                          
                      
                                            После этого вы можете использовать ограждение кода ```fomo, и ваш код будет подсвечен правильно!
                          
                      
                                            fomo hello_world(): "An example" pass