Блоки кода Markdown - шпаргалка и примеры использования

Здесь я рассматриваю варианты блоков кода в Markdown.

Блоки кода в Markdown

Блоки кода в Markdown - это способ отображения кода или предварительно отформатированного текста в документах Markdown, сохраняя форматирование и, при необходимости, обеспечивая подсветку синтаксиса. Существует два основных типа форматирования кода в Markdown: встроенный код и блоки кода.

Типы блоков кода в Markdown

Ключевые различия

• Встроенный код использует одинарные обратные кавычки (`) и предназначен для коротких фрагментов кода внутри предложения.
• Отступные блоки кода используют четыре пробела или табуляцию в начале каждой строки. Они не поддерживают подсветку синтаксиса и менее распространены в современном Markdown.
• Огражденные блоки кода используют тройные обратные кавычки (```) или тильды (~~~) до и после кода. Это предпочтительный метод, особенно на платформах вроде GitHub, потому что:
  • Они легче читаются и пишутся.
  • Вы можете указать язык программирования сразу после открывающих обратных кавычек для подсветки синтаксиса.
  • Они сохраняют форматирование и поддерживают многострочный код.

Пример огражденного блока кода с подсветкой синтаксиса:

Когда у нас есть следующий текст с форматированием Markdown:

```python
def hello():
    print("Hello, world!")
```

То отображаемый текст будет выглядеть так:

def hello():
    print("Hello, world!")

Лучшие практики использования блоков кода в Markdown

• Используйте огражденные блоки кода (тройные обратные кавычки) для многострочного кода, чтобы обеспечить четкость и совместимость на разных платформах.
• Указывайте язык после открывающих обратных кавычек для подсветки синтаксиса (например, ``````python).
• Используйте встроенный код для коротких фрагментов или команд внутри текста.
• Избегайте отступных блоков кода, если это не требуется для совместимости с устаревшими системами, так как они не поддерживают подсветку синтаксиса и могут быть менее читаемыми.
• Размещайте пустую строку до и после огражденных блоков кода для улучшения читаемости в исходном Markdown.

Специальные возможности

• Некоторые платформы поддерживают дополнительные идентификаторы языков, такие как diff для отображения изменений в коде, что позволяет выделять добавленные или удаленные строки в обзорах кода.
• Чтобы отобразить обратные кавычки внутри блока кода, оберните блок в большее количество обратных кавычек (например, четыре обратные кавычки для отображения трех).

Вывод

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

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

Чтобы эффективно использовать подсветку синтаксиса diff в блоках кода Markdown, следуйте этим шагам:

• Используйте огражденные блоки кода с тройными обратными кавычками (```) в начале и конце блока.
• Укажите diff как идентификатор языка сразу после открывающих обратных кавычек. Это включит подсветку синтаксиса для различий, подобную той, что вы видите в сообщениях коммитов Git или запросах на слияние.

Пример:

- старая строка, которая будет удалена
+ новая строка, которая будет добавлена
неизмененная строка

• Строки, начинающиеся с -, будут выделены как удаления (обычно красным).
• Строки, начинающиеся с +, будут выделены как добавления (обычно зеленым).
• Строки без префикса не будут специально выделены.

Лучшие практики:

• Используйте этот формат, чтобы четко сообщать об изменениях в коде, исправлениях или предложениях в документации, обзорах кода или технических блогах.
• Размещайте пустую строку до и после блока кода для лучшей читаемости в исходном Markdown.
• Обратите внимание, что подсветка diff окрашивает только целые строки на основе ведущего символа; она не выделяет изменения внутри строки.

Совет: Этот метод широко поддерживается на платформах вроде GitHub, GitLab и многих рендерерах Markdown, что делает его надежным выбором для визуального отображения изменений в коде.

Поддерживаемые языки

Блоки кода в Markdown поддерживают широкий ассортимент языков для подсветки синтаксиса, но точный набор поддерживаемых языков зависит от рендерера или платформы, которую вы используете. Сам Markdown не определяет, какие языки поддерживаются; он просто передает идентификатор языка движку рендеринга, который затем применяет соответствующую подсветку синтаксиса. Сами ограждения кода Markdown не определяют фиксированный набор официально поддерживаемых языков программирования. Вместо этого список поддерживаемых языков зависит от рендерера Markdown или платформы, которую вы используете (например, GitHub, GitLab, VS Code, Typora, Quarto и т.д.).

Часто поддерживаемые языки на крупных платформах (таких как GitHub, VS Code, Bitbucket, Docusaurus и ReadMe) включают:

• Веб и скрипты: javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Программирование: python (py), java, c, c++, c#, php, ruby, go, rust, scala, swift, kotlin, objective-c
• Данные и запросы: sql, r, matlab
• Разметка и конфигурация: markdown, ini, toml, dockerfile, makefile
• Специальные: diff, mermaid, geojson, topojson, stl (для диаграмм и визуализации данных на GitHub)
• Другие: jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme и многие другие

Как указать язык: Используйте имя языка сразу после открывающих тройных обратных кавычек:

```python
def hello():
    print("Hello, world!")
```

Следующие языки широко поддерживаются БОЛЬШИНСТВОМ рендереров Markdown:

Примечание: Фактический идентификатор может варьироваться (например, js против javascript). Большинство рендереров нечувствительны к регистру для имен языков.

Как найти полный список поддерживаемых языков:

• GitHub: Использует Linguist для подсветки, поддерживая сотни языков.
• VS Code и многие веб-рендереры: Используют highlight.js или Pygments - см. их документацию для полных списков.
• Bitbucket: Ссылается на режимы CodeMirror и лексеры Pygments.

Ключевые моменты:

• Большинство платформ поддерживают все основные языки программирования, скриптов и разметки.
• Некоторые платформы также поддерживают форматы диаграмм и данных (например, mermaid, geojson).
• Идентификатор языка обычно нечувствителен к регистру, но лучше использовать строчные буквы для наилучшей совместимости.
• Если вы используете не поддерживаемый идентификатор языка, блок кода будет отображаться как обычный текст.

Указание имени файла в блоке кода Markdown

Чтобы указать имя файла в блоке кода Markdown, у вас есть несколько вариантов, но метод зависит от платформы и рендерера:

1. Имя файла в метке блока кода (мета-синтаксис)

Некоторые движки Markdown (например, некоторые генераторы статических сайтов, инструменты для документации и блоговые платформы) поддерживают мета-синтаксис, где имя файла добавляется после языка, разделенное двоеточием:

```js:app.js
console.log("Hello, world!");
```

Это отобразит имя файла (например, app.js) выше или рядом с блоком кода, в зависимости от рендерера. А рендер этого сайта на Hugo не поддерживает этот функционал:

console.log("Hello, world!");

Примечание: Этот функционал не поддерживается на всех платформах (например, GitHub-flavored Markdown в настоящее время не поддерживает эту функцию).

2. Ручное добавление заголовка или встроенного кода

Для универсальной совместимости (включая GitHub, Stack Overflow и большинство рендереров Markdown) разместите имя файла выше блока кода, используя заголовок или жирный встроенный код:

**`app.js`**

```
console.log("Hello, world!");
```

Или:

#### `app.js`

```
console.log("Hello, world!");
```

Это визуально связывает имя файла с блоком кода и работает везде.

3. Имя файла как комментарий в коде

Альтернативно, вы можете включить имя файла как комментарий внутри самого блока кода:

```
// app.js
console.log("Hello, world!");
```

Это особенно полезно, если вы хотите, чтобы имя файла было видно при копировании кода.

Итог и лучшие практики

Используйте заголовок или жирный встроенный код выше блока кода для максимальной совместимости, и рассмотрите возможность добавления комментария внутри кода для ясности при обмене между разными платформами.

Полезные ссылки

• Шпаргалка по Markdown - самые полезные структуры и команды
• Шпаргалка по Hugo
• Шпаргалка по Bash - самые полезные команды bash
• Шпаргалка по LaTeX
• Самые популярные темы для Hugo
• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks