Оформление сниппетов кода в Markdown с подсветкой синтаксиса

Инлайн-код против блоков кода (Fenced code blocks)

В технических статьях, методичках и отчетах по лабораторным работам код встречается постоянно (рекомендуем также наше руководство по оформлению листингов кода в отчетах по ГОСТ). В Markdown предусмотрено два способа его визуализации: внутристрочный (инлайн) и многострочный блок (fenced block).

Для коротких переменных, имен функций или команд терминала используются одиночные обратные кавычки (бэктики): `const a = 10`. Для полноценных фрагментов программ применяются тройные кавычки ``` с обязательным указанием языка программирования.

Markdown подсветка кода для разных языков: таблица идентификаторов

Чтобы активировалась Markdown подсветка кода для разных языков, сразу после открывающих трех бэктиков указывается короткий идентификатор языка, который понимают библиотеки подсветки (Prism, Highlight.js):

```python
def calculate_energy(mass, c=299792458):
    """Расчет релятивистской энергии покоя"""
    return mass * (c ** 2)
```

Наиболее востребованные идентификаторы в академической среде:

• python или py — Python (автоматически подсвечиваются декораторы, строки документации и числа);
• cpp, c — C и C++ (ключевые слова, директивы препроцессора, указатели);
• javascript, js, typescript, ts — веб-разработка и скрипты;
• bash, sh, shell — консольные команды терминала;
• latex, tex — код макросов и окружений TeX;
• json, yaml, xml — конфигурационные файлы и форматы данных.

Как это выглядит в Labkeeper. Идентификатор языка стоит указывать, но цветной подсветки в Labkeeper нет: превью Markdown показывает блок моноширинным шрифтом без цвета, а в LaTeX-проекте блок кода из Markdown-сегмента становится обычным моноширинным блоком. Цветные ключевые слова, нумерацию строк и подпись «Листинг» в PDF дает пакет listings в LaTeX-сегменте — настройка разобрана в статье об оформлении листингов кода в отчетах по ГОСТ.

Синтаксис кода в Markdown: отступы, экранирование и бэктики

Если вам требуется показать сам синтаксис кода в Markdown (включая тройные кавычки) внутри примера, используйте внешнее обрамление из четырех бэктиков или делайте отступ в 4 пробела:

````markdown
Здесь показан пример разметки:
```python
print("Hello world")
```
````

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

Особенности отображения листингов при сохранении в PDF

В распечатанном отчете длинные строки листинга не должны вылезать за границы листа А4. В превью Labkeeper блок кода набирается системным моноширинным шрифтом браузера, а длинная строка не переносится: блок прокручивается по горизонтали. При сохранении в PDF через печать браузера такая строка обрежется по краю листа, поэтому длинные инструкции переносите вручную, например после запятой или оператора.

Если нужен листинг с автоматическим переносом строк, нумерацией и подписью, используйте LaTeX-проект и пакет listings с параметрами breaklines=true и numbers=left.

Типичные ошибки при оформлении кода

• Использование обычных одинарных кавычек: Символы ''' не открывают блок кода в Markdown. Требуются только грависы (обратные кавычки ```, клавиша Ё в английской раскладке).
• Незакрытый блок: если забыть закрывающие ```, весь текст до конца сегмента превратится в код.

Практические советы