Markdown Руководство по блокам кода: код в строке, блоки с ограждением и выделение синтаксиса

Форматирование кода является одной из самых сильных функций Markdown. Независимо от того, документируете ли вы функцию, показываете команду терминала или пишете учебник, синтаксис Markdown сохраняет визуально отличный код. правильно отформатированы и (на большинстве платформ) выделены синтаксисом. Это руководство охватывает все, что касается Markdown блоки кода.

Код в строке

Завернуть короткий фрагмент или одно выражение в однократные спинки:

Use `console.log()` to print output.
Set the variable with `const x = 42;`.
The file is saved as `README.md`.

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

• Названия функций и методов: addEventListener()
• Наименования переменных: isLoading
• Имена файлов: package.json
• Аргументы команды: --verbose
• Краткие выражения кода

Если ваш код содержит обратную ссылку, используйте двойные обратные ссылки для ее завершения:

`` `backtick inside` ``

Огражденные блоки кода

Для многострокового кода для открытия и закрытия блока используйте тройные обратные знаки (`):

```
This is a code block.
It preserves all whitespace and line breaks.
No formatting is applied inside.
```

Внутренние оттиски, расстояния и новые линии сохраняются точно.

Выделение синтаксиса

Добавить идентификатор языка после открытия тройной обратной колонки для включения подчеркивания синтаксиса:

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("World"))
```

```javascript
const greet = (name) => `Hello, ${name}!`;
console.log(greet("World"));
```

```bash
#!/bin/bash
echo "Hello, World!"
ls -la ~/Documents
```

Общие языковые идентификаторы

Блоки кода с зачеркновением

В более старой синтаксисе Markdown используется 4-пространственное запятая для блоков кода:

    function oldStyle() {
        return "This is a code block";
    }

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

Преобразование кода из _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

Текст монопространства в Word (Courier New, Consolas и т.д.) преобразуется в код в строке, когда вы используете WordToMD. Multi-line code in Word converts depending on how it was formatted:

• Параграф монопространственного шрифта → Может стать множеством фрагментов кода
• Word Стиль кода → Преобразует в блок кода
• Буквальный блок текста → Может потребоваться ручное ограждение

После преобразования проверьте разделы кода и при необходимости добавьте соответствующие ограждения:

1. Найти код, который должен быть блоком
2. Заверните его тройной спинкой .
3. Добавить соответствующий языковой идентификатор

Примеры, относящиеся к конкретному языку

HTTP-запросы

```http
POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer TOKEN

{
  "name": "Alice",
  "email": "alice@example.com"
}
```

Команды терминала

```bash
npm install
npm run build
npm run dev
```

Выпуск дифференциации

```diff
- const oldValue = "hello";
+ const newValue = "world";
  console.log(newValue);
```

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

```yaml
server:
  host: localhost
  port: 8080
  debug: true
database:
  url: postgresql://localhost:5432/mydb
```

Блоки вложенного кода (для документации)

При документировании самого Markdown используйте 4 бакттикса для завершения блока, который содержит 3 бакттикса:

````markdown
```python
# This is a code block inside documentation
```
````

Поддержка платформы

Номера строк

Стандарт Markdown не поддерживает номера строк в блоках кода. Некоторые платформы и генераторы статических сайтов добавляют это через плагины:

• Prism.js (используется многими СГС) добавлять {numberLines: true} в кодовом ограждении
• GitHub отсутствуют номера линий в отображаемом Markdown (вместо этого используйте GitHub Вид вины)
• GitBook номера строк через настройки блока кода

Копирование кода из блоков

GitHub и многие платформы добавляют кнопку Copy к блокам кода автоматически. Это усовершенствование рендеринга, не требует ничего особенного в вашем Markdown.

FAQ

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

Как я показываю задницы внутри кодового блока? Внутри огражденного кодового блока задние кнопки рассматриваются как буквальные символы. Только ограждение с тремя спинками нуждается в специальной обработке.

В моем документе Word был красочный синтаксис с подчеркнутым кодом. Сохранит ли WordToMD цвета? Нет Markdown блоки кода не сохраняют цветовое форматирование. WordToMD преобразует текст в блок кода; подчеркивание синтаксиса затем применяется _Markdown на основе идентификатора языка.

Могу ли я выделить конкретные линии в блоке кода? Стандарт Markdown не поддерживает это. Некоторые платформы (например, Astro с Shiki или Hugo) поддерживают линию, выделяющую через комментарии: {1,3-5} после идентификатора языка.

Соответствующие руководства

• Markdown Синтаксис краткая памятка Полная ссылка
• Word до API Документация Документация с большим количеством кодов
• Word к GitHub Markdown GitHub-специфическое форматирование кода

Заключение

Блоки кода маркировки просты: backticks для встроенного кода, тройные backticks с языковым идентификатором для блоков. После преобразования Word документа с помощью WordToMD, проверить, правильно ли текст монопространства зашифрован в синтаксисе кода, и добавлять языковые идентификаторы для правильного выделения синтаксиса на целевой платформе.