Генератор ссылок Markdown

Четыре варианта ссылок

Встроенный, без заголовка:

[Читать документацию](https://example.com/docs)

Встроенный с заголовком (всплывающая подсказка при наведении):

[Читать документацию](https://example.com/docs "Полная документация")

Ссылочный стиль (URL определён ниже):

Откройте [документацию][docs] или [журнал изменений][cl].

[docs]: https://example.com/docs
[cl]:   https://example.com/changelog

Автоссылка (URL является одновременно текстом и целью):

<https://example.com>

Когда какой вариант выбрать

• Встроенный, для нечастых ссылок, где URL короткий и абзац по-прежнему хорошо читается.
• Ссылочный стиль, когда вы приводите один и тот же URL несколько раз или когда URL представляет собой отслеживающего монстра на 200 символов, который иначе нарушил бы течение абзаца.
• Автоссылка, для случая «вот наша страница документации», когда вы хотите, чтобы URL был виден и как текст, и как цель.

Обработка специальных символов

• Пробелы в URL требуют %20, иначе ссылка обрывается на пробеле.
• Круглые скобки в URL требуют URL-кодирования как %28 и %29, иначе парсер Markdown их проглотит.
• Квадратные скобки в тексте ссылки нужно экранировать как \[ и \], чтобы парсер не воспринял их как вложенный синтаксис ссылки.

Советы по доступности

• Избегайте «нажмите здесь». Текст ссылки вроде нажмите здесь или читать далее бесполезен, когда пользователи программ чтения с экрана перебирают ссылки табуляцией. Используйте описательный текст: [руководство по установке](...).
• Не используйте сам URL в качестве текста ссылки для длинных URL, это неудобно для вспомогательных технологий и некрасиво выглядит в печати.
• «Открыть в новой вкладке», это сырой HTML (target="_blank"), а не Markdown. Большинство обработчиков, принимающих сырой HTML, учтут его; чистый CommonMark, нет.

Однострочный приём

В комментариях на GitHub вставка URL рядом с выделенным текстом автоматически превращает его в ссылку Markdown. Удобно, когда вы уже находитесь в редакторе.