Markdown, Doc, Code

Markdown, Doc, Code

https://giga.chat/link/gcstlnYZRz

2. Почему это принято в индустрии

В современной разработке принято правило «документация живет рядом с кодом» (Documentation as Code).

• Текстовые файлы .md можно положить в систему контроля версий (Git) вместе с самим кодом.
• При каждом изменении архитектуры разработчик меняет текст в том же коммите, что и код. Документация никогда не устаревает.
• Такие файлы легко превращаются в красивый сайт со справочником (например, с помощью генератора DocFX или MkDocs), где блоки кода будут аккуратно подсвечены.

--------------

Инструменты для визуализации архитектуры (внутри Markdown):

• PlantUML и Mermaid: это языки для рисования диаграмм обычным текстом. Вы пишете текст в блоке кода, а в предпросмотре видите готовую картинку. Пример Mermaid для вашей задачи: ```mermaid graph TD A[Trading.Web] --> B[Trading.Gateway] B --> C[Trading.Api.Orders] B --> D[Trading.Api.MarketData] 

----------------------------------------------------------------------------------------------------

Для комфортной работы с документацией в VSCode достаточно знать базовый синтаксис Markdown. Редактор мгновенно отображает результат в окне предпросмотра (Ctrl+Shift+V или Ctrl+K V).

Ниже приведен подробный справочник основных символов и команд.

1. Структура и заголовки

Заголовки создаются с помощью символа #. Количество решеток определяет уровень заголовка (от H1 до H6).

markdown

# Заголовок 1 (H1) — Название документа
## Заголовок 2 (H2) — Крупный раздел
### Заголовок 3 (H3) — Подраздел

Совет: Для горизонтальной линии-разделителя используйте три дефиса или три звездочки на отдельной строке: --- или ***.

2. Текст и акценты

Элемент	Синтаксис	Результат
Жирный	**текст** или __текст__	текст
Курсив	*текст* или _текст_	текст
Жирный курсив	***текст***	текст
Зачеркнутый	~~текст~~	текст
Моноширинный	`текст`	Моноширинный

3. Списки

Маркированный список (просто точки):

markdown

- Пункт 1
- Пункт 2
  - Подпункт (два пробела перед дефисом)
- Пункт 3

Альтернативные маркеры: * или +.

Нумерованный список:

markdown

1. Первый шаг
2. Второй шаг
   1. Вложенный нумерованный список
3. Третий шаг

Важно: Цифры могут быть одинаковыми (1., 1.), Markdown сам их пересчитает.

Список дел (чекбоксы):

markdown

- [x] Задача выполнена
- [ ] Задача в работе

4. Ссылки и изображения

Обычная ссылка: [Текст ссылки](https://example.com) Подсказка: Если вставить в VSCode ссылку из буфера обмена на выделенный текст, редактор сам обернет ее в скобки.

Ссылка со всплывающей подсказкой: [Текст](адрес "Всплывающая подсказка")

Изображение: ![Альтернативный текст (если картинка не загрузится)](путь/к/картинке.png) Совет: Для скриншотов в документации лучше создать папку images/ рядом с .md файлом и ссылаться на нее: ![Схема архитектуры](images/architecture.png).

Относительные ссылки на другие документы: [Описание контрактов](docs/contracts.md)

5. Блоки кода (самое важное для вас)

Именно здесь решается проблема с волнистыми линиями.

Встроенный код (внутри предложения): Используйте одиночные обратные кавычки: Для класса используйте метод \OrderService.Calculate()`.`

Многострочный блок кода: Используйте тройные обратные кавычки ```. Обязательно указывайте язык сразу после них — это включает подсветку синтаксиса и отключает проверку Markdown-текста на ошибки C#.

Для описания архитектуры и псевдокода (чтобы не было никакой подсветки): ```text Trading.Web | v Trading.Gateway | +--> Trading.Api.Orders ```

Для C# кода: ```csharp public class Gateway { public void Route() { } } ```

Для командной строки (Bash): ```bash dotnet run --project Trading.Gateway ```

Для JSON: ```json { "symbol": "SBER", "price": 280.50 } ```

6. Таблицы

Создаются с помощью дефисов - и вертикальных черт |. Дефисы задают выравнивание:

markdown

| Элемент | За что отвечает | Пример |
|:---|:---|:---|
| TScheduler | **Когда** (расписание) | Cron 0 9 * * 1 |
| TBehavior | **Что делать** (логика) | SendEmailJob |
| TTune | **Нюансы** (пороги) | Timeout=5000 |
| Left | По левому краю | Текст |
| Center | По центру | Текст |
| Right | По правому краю | 123.45 |

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

7. Цитаты и заметки

markdown

> Это блок цитаты. Часто используется для выносок.
> 
> Внутри цитаты работают **все** остальные правила Markdown.

Для создания красивых заметок (важно, предпросмотр VSCode их поддерживает, а GitHub — нет, но они отлично работают в генераторах типа DocFX):

markdown

> [!NOTE]
> Полезная информация или контекст.

> [!WARNING]
> Критическое предупреждение.

> [!TIP]
> Совет по оптимизации.

8. Горячие клавиши VSCode для Markdown

• Ctrl+K V — открыть предпросмотр в соседней вкладке.
• Ctrl+Shift+V — открыть предпросмотр во всплывающем окне.
• Ctrl+B — сделать выделенный текст жирным (VSCode сам вставит **).
• Ctrl+I — сделать выделенный текст курсивом (вставит *).
• Ctrl+Shift+P -> введите Markdown: Create Table of Contents — расширение Markdown All in One автоматически создаст оглавление по всем заголовкам в начале файла.
• Enter после элемента списка — VSCode автоматически продолжит список с новым номером или маркером.
• Ctrl+Enter в списке — создаст новый пункт списка.

9. Как избежать ошибок редактора

Если VSCode все равно подчеркивает текст (например, из-за установленного расширения markdownlint):

1. Кликните на подчеркнутое слово.
2. Нажмите на лампочку (Ctrl+.).
3. Выберите Disable line for markdownlint или Disable rule 'no-trailing-spaces' for this file.
4. Либо в начале файла добавьте комментарий, отключающий линтинг: <!-- markdownlint-disable -->

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