markdown linting accessibility руководство по стилю documentation

Линтинг Markdown: 15 частых проблем и способы их исправить

Найдите и устраните распространенные проблемы Markdown, включая пропущенные заголовки, отсутствующий замещающий текст изображения, пустые URL-адреса, нарушенные ограничения кода, противоречивые списки и неверные таблицы.

W
WordToMD Команда
·

Markdown является разрешающим.Документ со структурными ошибками все равно может отображаться, поэтому эти ошибки легко пропустить, пока таблица не сломается, заголовок не исчезнет из навигации или изображение не станет бессмысленным для пользователя программы чтения с экрана.

Markdown Линтинг — это процесс проверки исходного текста на наличие проблем в структуре, доступности и согласованности перед публикацией.Начните с Линтер Markdown для обнаружения пропущенных уровней заголовков, отсутствующего замещающего текста изображения, пустых URL-адресов, непомеченных или незакрытых границ кода и конечных пробелов.Затем используйте контрольный список в этом руководстве для более широкого редакционного обзора.

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

Краткий контрольный список перед публикацией

ПроверкаПочему это важноАвтоматически или вручную?
Иерархия заголовковСохраняет структуру документа.Линтер
Замещающий текст изображенияДелает изображения понятными невооруженным глазом.Линтер
Описательные ссылкиУлучшает доступность и сканирование.Линтер + обзор мануала
Закрытые кодовые огражденияПредотвращает превращение остальной части страницы в кодЛинтер
Ярлыки языка кодаВключает полезную подсветку синтаксиса.Линтер
Конечные пробелыИзбегает невидимого, специфичного для диалекта поведения.Линтер
Один понятный заголовок страницыСохраняет однозначность назначения страницыРучной просмотр
Согласованные спискиПредотвращает нарушение раскрояРучной просмотр
Действительные таблицыСохраняет структуру столбца неповрежденнойРучной просмотр
Уникальные заголовкиПредотвращает путаницу при дублировании якорей.Ручной просмотр
Использование портативного HTMLПредотвращает сбои, связанные с рендерингомРучной просмотр
Читабельные параграфыУлучшает пониманиеРучной просмотр

Вставьте репрезентативный документ в линтер, запустите проверки, исправьте обнаруженные строки, а затем просмотрите всю страницу в фактической системе публикации.

1. Пропущенные уровни заголовков

Проблема

# Deployment Guide

### Configure credentials

Документ переходит с H1 на H3.Это может выглядеть приемлемо, когда размер шрифта является единственным видимым сигналом, но в структурном контуре отсутствует определенный уровень.

Исправление

# Deployment Guide

## Configure credentials

Используйте заголовки для описания иерархии, а не для выбора визуального размера.Если «Настройка учетных данных» действительно находится в отсутствующем разделе, добавьте этот раздел:

# Deployment Guide

## Preparation

### Configure credentials

В связи с Линтер Markdown сообщает о заголовке, который перемещается более чем на один уровень.

2. Несколько или отсутствие заголовков H1

Обычно страница должна иметь один понятный заголовок.Некоторые системы документации генерируют H1 из начального текста, в то время как другие ожидают его в теле Markdown.Узнайте, какое соглашение использует ваш сайт.

Неоднозначный источник

# Installation

# Configuration

Очистить источник

# Product setup

## Installation

## Configuration

Если шаблон вашего сайта отображается title: Product setup в качестве страницы H1, вместо этого тело может начинаться с H2.Правило не гласит: «Каждый файл Markdown должен содержать ровно один #.” The rule is “the rendered page needs one unambiguous primary heading.”

3. Заголовки используются только для выделения

Этот источник создает ненужную запись в структуре:

#### Important!

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

**Important:** Back up the database before continuing.

Заголовки должны помогать читателям ориентироваться.Декоративные заголовки загромождают оглавление и снижают полезность вспомогательной навигации.

4. Изображения без альтернативного текста

Проблема

![](architecture.png)

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

Исправление

![Request flow from the browser through the API gateway to the orders service](architecture.png)

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

Декоративные изображения представляют собой особый случай.Пустой замещающий текст может быть корректным в HTML, если изображение не несет никакой информации, но средства визуализации Markdown и рабочие процессы с контентом различаются.Если изображение чисто декоративное, сначала спросите, принадлежит ли оно вообще технической документации.

Линтер помечает изображения Markdown пустым замещающим текстом. Форматирование изображений может генерировать разметку изображения с явным альтернативным и необязательным заголовком.

Проблема

Visit https://example.com/docs/setup for more information.

Голые URL-адреса трудно сканировать, и их чтение вслух может быть неприятным.Общий текст ссылки не намного лучше:

[Click here](https://example.com/docs/setup).

Исправление

Read the [service setup guide](https://example.com/docs/setup).

Описательные ссылки сообщают читателям, что они откроют.Они также сохраняют смысл, если их извлечь в список ссылок.

Линтер выявляет множество голых http:// and https:// URL-адреса, но редакционная проверка по-прежнему необходима, чтобы определить, полезен ли текст ссылки.

6. Незакрытые кодовые ограждения

Проблема

```javascript
const status = 'ready';

## Next section

Без закрывающего ограждения средство визуализации может рассматривать остальную часть страницы как код.

Исправление

```javascript
const status = 'ready';
```

## Next section

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

7. Ограждения кода без языковых идентификаторов

Менее полезно

```
npm run build
```

Лучше

```bash
npm run build
```

Идентификатор языка включает подсветку синтаксиса и сообщает, какой контент видит читатель.Используйте общие идентификаторы, такие как javascript, typescript, json, html, css, bash, powershell, yamlили markdown.

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

8. Несогласованный отступ списка

Проблема

- Install dependencies
    - Production packages
  * Development packages
	- Optional tools

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

Исправление

- Install dependencies
  - Production packages
  - Development packages
  - Optional tools

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

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

9. Числовые последовательности, вводимые вручную

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

1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.

Многие средства визуализации Markdown позволяют использовать каждый элемент. 1. , продолжая отображать упорядоченную последовательность:

1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.

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

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

10. Неверные таблицы

Проблема

| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |

Разделитель и строки данных не содержат одинаковое логическое количество столбцов.

Исправление

| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |

Также проверьте наличие неэкранированных символов вертикальной черты внутри ячеек:

| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |

В связи с Форматирование таблиц Markdown помогает выявить неровные строки и создать выровненный источник.Для визуального создания новой таблицы используйте команду Markdown Генератор таблиц.

11. Повторяющиеся заголовки и коллизии привязок

Документ может законно повторять видимый заголовок, например «Примеры», но автоматически сгенерированные идентификаторы привязки могут стать #examples, #examples-1и #examples-2.Точное правило зависит от рендерера.

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

- [API examples](#examples)
- [CLI examples](#examples)

Отдавайте предпочтение описательным заголовкам:

## API examples

## CLI examples

Затем создайте оглавление с помощью Markdown Генератор TOC и проверьте крепления на целевой платформе.

12. Конечные пробелы

Пробелы в конце строки невидимы.В некоторых диалектах Markdown два конечных пробела создают жесткий разрыв строки, что означает, что случайное действие редактора может изменить рендеринг.

Линтер сообщает о конечных пробелах, чтобы вы могли решить, намеренно ли это.Предпочитайте пустую строку для разделения абзацев.Если резкий разрыв действительно необходим, документируйте и последовательно применяйте выбранное соглашение проекта.

Редакторы обычно могут автоматически удалять конечные пробелы при сохранении, но убедитесь, что это не приводит к изменению преднамеренных разрывов строк в устаревшем контенте.

13. Необработанный HTML, снижающий переносимость

Markdown часто допускает встроенный HTML:

<div class="warning-panel">
  Restarting the service ends active sessions.
</div>

Этот блок может работать на одном веб-сайте и быть экранированным, очищенным или иметь неправильный стиль в другом месте.Предпочитайте переносной Markdown, если он может выражать то же значение:

> **Warning:** Restarting the service ends active sessions.

Намеренно используйте HTML для функций, которые Markdown не могут быть выражены, например, контролируемый размер изображения или поддерживаемый <details> .Составьте список мест назначения, в которых контент должен отображаться, и протестируйте каждое из них.

В связи с Генератор выносок может создавать специфичный для платформы синтаксис для GitHub, Obsidian и MkDocs, когда переносимость менее важна, чем собственное представление.

14. Слишком длинные абзацы и плохая сканируемость

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

Использование:

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

Не превращайте каждое предложение в пулю.Списки работают лучше всего, когда элементы имеют одинаковую грамматическую и концептуальную роль.

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

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

Списки задач GitHub, вики-ссылки Obsidian, предостережения MkDocs, сноски, списки определений и вступительная часть — все они полезны, но поддерживаются не везде одинаково.

Например:

> [!NOTE]
> This callout is useful in destinations that recognize the syntax.

Прежде чем принять расширение, ответьте на три вопроса:

  1. Какому средству визуализации принадлежит окончательный результат?
  2. Нужно ли позже перенести контент в другое место?
  3. Что увидят читатели, если расширение не поддерживается?

Сохраняйте переносимую основу Markdown и по возможности добавляйте синтаксис платформы на уровне публикации.

Практический процесс линтинга

Шаг 1: Проверьте структуру

Вставьте исходный код в Линтер Markdown.Сначала исправляйте ошибки, затем предупреждения, а затем элементы информационной согласованности.Автоматизированные проверки должны определять местоположения;они не должны молча переписывать смысл.

Шаг 2. Нормализация сложных элементов

Используйте специальные инструменты для механической очистки:

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

Шаг 3: Предварительный просмотр документа

Откройте исходный код в Markdown Редактор и сравните Markdown с визуализированным результатом.Проверьте:

  • заголовки и оглавление;
  • списки и списки задач;
  • столы на узком экране;
  • изображения и ссылки;
  • кодовые блоки и встроенный код;
  • или необработанный HTML.

Шаг 4: Проверьте реальный пункт назначения

Общий предварительный просмотр не может воспроизвести все средства визуализации.Перед публикацией откройте файл в GitHub, Obsidian, GitLab, MkDocs или на реальном сайте документации.

Шаг 5. Проверьте значение, а не только синтаксис

Ни один линтер не может определить, безопасна ли процедура, ссылка указывает на намеченную политику или описание изображения сообщает важный вывод.Рецензент должен подтвердить точность, полноту, тон и соответствие аудитории.

Рекомендации руководства по стилю команды

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

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

Начните с правил, предотвращающих реальные дефекты.Добавляйте правило только тогда, когда команда понимает проблему, которую оно решает.

FAQ

Действительно ли Markdown доступен автоматически?

Нет. Действительный синтаксис по-прежнему может содержать пустой замещающий текст, неясные ссылки, запутанные заголовки, недоступные диаграммы и плохой порядок чтения.Доступность требует структурного и редакционного анализа.

Перепишет ли Линтер Markdown мой документ?

Линтер WordToMD сообщает о проблемах с нумерацией строк.Он не перезаписывает исходный код автоматически, поэтому вы сохраняете контроль над каждым исправлением.

Почему линтер выдаёт пустой URL?

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

Всегда ли немаркированный кодовый барьер неправильный?

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

Должны ли все проекты использовать одни и те же правила линтинга?

Нет. GitHub README, хранилище Obsidian, ссылка API и сайт публикации имеют разные соглашения.Поделитесь основным набором структурных правил и правил доступности, а затем добавьте проверки для конкретных мест назначения.

Может ли линтинг заменить корректуру?

Нет. Линтер обнаруживает закономерности.Он не может надежно проверить техническую истинность, качество аргументации, намерения пользователя или понятность предложения в контексте.

Заключение

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

Запустите Линтер Markdown для быстрых структурных проверок используйте команду Markdown Редактор для визуального просмотра и применяйте специализированные средства форматирования только там, где они упрощают обслуживание источника.В результате получается Markdown, более портативный, доступный и надежный при будущих изменениях.