как выделить код в markdown

MarkedText — маркдаун здорового человека

Вёрстка несколько поехала, так как на Хабре выкатили новый кривой визивиг. Так что теперь писать статьи в маркдауне, а потом выкладывать на Хабр будет крайне сложно. С нормальной вёрсткой эту статью вы можете почить на гитхабе: https://github.com/nin-jin/HabHub/issues/39

Принципы

Минимальное влияние на естественный вид текста

Удобство редактирования независимо от раскладки

Быстрая и надёжная запоминаемость

Существующие решения

В английской Википедии есть сравнительный обзор легковесных языков разметки, так что не будем повторяться. Там приведены следующие языки: AsciiDoc, BBCode, Creole, GitHub Flavored Markdown, Markdown, Markdown Extra, MediaWiki, MultiMarkdown, Org-mode, PmWiki, POD, reStructuredText, Textile, Texy, txt2tag.

Текстовые блоки

Блоки текста будем разделять двойным переводом строки, что даст визуальный отступ между блоками. Тип блока определяется специальным префиксом в начале каждой строки блока. Если префикс не распознан, то это обычный абзац.

Списки

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

Элементы неупорядоченного списка предваряются маркером. По нормам многих языков таким маркером выступает тире. В вебе в основном потребляются «буллеты». В облегчённых языках разметки в основном используются следующие:

first of first of second

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

first of first of second

Цитаты

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

Таблицы

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

Заголовки

В некоторых языках заголовки выделяются разными типами подчёркиваний:

Есть более удобная форма, где уровень заголовка определяется числом спецсимволов в префиксе:

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

Преформатированный текст

В некоторых языках для преформатированного текста используются специальные кавычки:

Однако, если в таком тексте тоже нужно вывести эти кавычки, то получается облом. Поэтому предпочтительнее вариант с префиксом перед каждой строкой. Например, в качестве такого префикса может выступать отступ, равный 2 или 4 пробелам:

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

В преформатированном тексте важен каждый символ, поэтому внутри него не может быть никакого форматирования. Однако, часто в повествовательных целях необходимо выделить какие-то строки или пометить их удалёнными/добавленными.

Поэтому мы разделим префикс на две части:

Маркер преформатированного текста из 2 пробелов.

Маркер форматирования строки из пары спец символов.

Выглядеть оно будет так:

Инлайн форматирование

Акценты

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

Варианты сильного акцента:

Варианты слабого акцента:

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

Правки

Порой надо выделить часть текста, как удалённую, а часть как добавленную. Зачастую это выглядит как зачёркнутый и подчёркнутый текст. Оба варианта в той или иной мере осложняют чтение, поэтому предпочтительнее использовать для этого подсветку фона, как это делают инструменты для мержа. Но в этом случае символы подчёркивания и дефисы уже перестают ассоциироваться с соответствующим им типом форматирования.

Итак, типичные формы выделения добавлений:

Добавления и удаления естественным образом независимо от визуализации ассоциируются с плюсом и минусом, так что воспользуемся именно ими:

Ссылки

Ссылки бывают двух видов:

Гиперссылки выглядят в разных языках так:

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

Для гиперссылок же воспользуемся \ во всех местах:

Разумеется разные типы ссылок можно комбинировать. Например, сделать картинку-ссылку можно так:

Инлайн код

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

Резюме

Теперь давайте соберём все конструкции формата в одной короткой шпаргалке:

Источник

Огонёк

Markdown (маркдаун) — облегчённый язык разметки созданный с целью написания максимально читабельного и удобного для правки текста, но пригодного для преобразования в языки для продвинутых публикаций (HTML, Rich Text и др.). Ниже будет приведена шпаргалка по синтаксису markdown со всеми самыми популярными тегами маркдаун.

Содержание в виде ссылок по тексту (якоря) (работает не со всеми плагинами wordpress)

Якоря в Markdown (маркдаун)

Тэг читать далее (cut) в Markdown (маркдаун)

Чтобы в маркдауне поставить тэг Читать далее, достаточно в строчке написать

Заголовки

Для того чтобы написать заголовок в Markdown, необходимо использовать знак # (хэш). Если необходимо несколько уровней заголовков, h1 — h6, нужно изменить количество хэшей (#) перед текстом заголовка.

Альтернативные теги для H1 и H2 (знаки равно или минусы под заголовком + пустая строчка над загаловком):

Альтернативный-H1

Альтернативный-H2

Списки

Горизонтальные линии

Создать горизонтальную линию можно поместив три или больше звездочек *, минусов — или подчеркиваний _ на отдельной строке.

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

Каждая из приведенных выше строк даст одинаковый результат. Вот такой:

Абзацы, параграфы

В маркдаун все блочные элементы (заголовки, списки, абзацы и т.д.) — все, что визуально начинается с новой строки отбивается пустой строкой. Для вставки пустой строки необходимо два раза поставить символ переноса строки (нажать на Enter)

Перенос строки

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

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

Для переноса строки внутри абзаца нужно использовать два пробела ⋅⋅ в конце строки.

Курсивное и жирное выделение текста

Для курсива необходимо поставить знаки * вокруг текста. Для жирного начертания обрамим текст двумя звездочками, а для жирного курсива — тремя. Алтернативный синтаксис — использование знака _ по тем же правилам.

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

Выделить текст или часть кода можно с помощью символа гравис (обратный апостроф)

Отмена форматирования

Если вы хотите, чтобы введенные теги HTML, код, теги маркдауна отображались в точности как вы их написали, то начните каждую строку с четырех пробелов.

Цитаты

Для обозначения цитат достаточно поставить знак > в начале строки

Это простая цитата
Состоящая из двух строк

(напомню, для переноса строчки я использую два пробела в конце строчки)
Цитаты можно вкладывать друг в друга:

Ссылки

Существует два варианта оформления ссылок. Первый — обычная вставка в текст:

и второй вариант — оформление ссылки в виде сноски. Когда в текст вставляется конструкция вида:

… Указывающая, что именно в этом место будет располагаться ссылка, а где-нибудь ниже её описание:

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

I get 10 times more traffic from Google than from
Yahoo or MSN.

Сноски

Сноски и примечания 1 задаются так 2 :

Изображения

Вставка реального изображения может выглядеть как-то так:

Создадим картинку, которая является еще и ссылкой на какую-нибудь страницу в сети:

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

Нужно помнить, что приведенные выше ссылки должны быть определены где-либо в документе:

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

Таблицы (работает не со всеми плагинами wordpress)

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

Спецсимволы

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

Списки определений

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

Moodle Хорошо известная платформа для онлайнового обучения PHP Язык программирования.
Часто используется для разработки интерактивных веб-приложений.

Спойлер (работает не со всеми плагинами wordpress)

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

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

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

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

Источник

Справка по Markdown

Код и предварительно отформатированный текст

Сделайте отступ в четыре пробела, чтобы создать изолированный блок

Вы также можете выделить текст и нажать CTRL + K чтобы выделить его как код или снять выделение.

Текст будет обёрнут тегами и отображён с использованием моноширинного шрифта. Первые четыре пробела будут обрезаны, но все остальные пробелы будут сохранены.

Markdown и HTML игнорируются внутри блока кода:

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

Строки кода

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

(Обратная кавычка обычно находится слева вверху под клавишей Esc.)

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

Если в самом коде находится обратная кавычка, вам придётся повторить её несколько раз в качестве разделителя:

Разрывы строк

Закончите строку 2 пробелами или добавьте разрыв строки
:

Курсив и полужирный

Вы также можете выделить текст и нажать CTRL + I или CTRL + B чтобы переключить у текста наклонное или полужирное начертание соответственно.

Ссылки

Основные ссылки

Существуют три способа вставки ссылок. Последний читается сложнее всего:

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

Расширенные ссылки

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

Можно также использовать стандартный синтаксис HTML для гиперссылок.

Чистые URL-адреса

Мы изменили анализатор Markdown, и теперь он поддерживает чистые URL-адреса (в большинстве случаев, но не всегда — обращайте внимание на необычные символы в URL-адресах); они автоматически будут преобразованы в ссылки:

Явно обозначайте URL-адреса, помещая их в угловые скобки:

URL-адреса могут быть либо относительными или абсолютными

Заголовки

Подчеркните текст, чтобы создать два заголовка верхнего уровня

Вы также можете выделить текст и нажать CTRL + H для переключения разных стилей заголовков.

Количество символов «=» или «-» не имеет значения; одного будет достаточно. Но при использовании большего числа знаков заголовки будет проще найти в основном тексте.

Используйте символ # для обозначения уровней заголовков:

Закрывающие символы # не обязательны.

Горизонтальные линии

Горизонтальная линия вставляется тремя или более дефисами, звёздочками или подчеркиваниями подряд:

Вы также можете нажать CTRL + R для вставки горизонтальной линии.

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

Вы также можете нажать CTRL + R для вставки горизонтальной линии.

Простые списки

Вы также можете выделить текст и нажать CTRL + U или CTRL + O чтобы сделать маркированный или нумерованный список соответственно.

Список с двойным междустрочным интервалом:

Расширенные списки: Вложение

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

Простые цитаты

Добавьте значок > в начало строки, чтобы создать цитату.

Вы также можете выделить текст и нажать CTRL + Q чтобы поместить его в цитату или убрать цитирование.

Расширенное цитирование: Вложение

Чтобы поместить другие блоки Markdown в цитату, просто добавьте символ > и пробел после него.

Чтобы поместить другие блоки Markdown в цитату, просто добавьте символ > и пробел после него:

Цитаты внутри цитаты:

Списки внутри цитаты:

Предварительно отформатированный текст в цитате:

Изображения

Изображения оформляются так же, как и ссылки, но перед ними стоит восклицательный знак:

Вы также можете нажать CTRL + G для вставки изображения.

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

Как и ссылки, картинки поддерживают синтаксис сносок и заголовки:

Внимание: Markdown не поддерживает сокращённый синтаксис для изображений:

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

Имя ссылки также используется как alt-текст.

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

URL-адреса могут быть либо относительными или абсолютными

Встраиваемый HTML

Если вы не можете сделать что-то через Markdown, используйте HTML. Учтите, что большинство опасных тегов отключено!

Markdown не будет вносить изменения в HTML-код на уровне строк:

Блочные элементы HTML имеют несколько ограничений:

Нужна более подробная информация?

Дополнения Stack Exchange

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

Метки

Для обсуждения метки на данном сайте, например-такой, используйте

Метка будет автоматически связана с соответствующей метке страницей.

Спойлеры

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

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

Блоки кода будут подсвечиваться, используя highlight.js. В большинстве случаев язык для подсветки синтаксиса будет выбираться из списка меток вопроса.

Чтобы вручную указать язык для блока кода, выделенного границами, добавьте язык в строку с открывающей границей:

Чтобы указать язык подсветки синтаксиса для ВСЕХ следующих блоков кода используйте:

Чтобы указать, что для данного блока кода не нужна подсветка синтаксиса, используйте:

Таблицы

Выравнивание

Вы можете задать выравнивание столбца таблицы добавив : в соответствующую ячейку разделительной линии. Символ : слева сделает столбец выравненным влево (по умолчанию). Символ : справа сделает столбец выравненным вправо. Добавление : с двух сторон приведёт к выравниванию по центру.

Подробнее о синтаксисе

Форматирование комментариев

Комментарии поддерживают только курсив, полужирный шрифт, код и несколько сокращений для ссылок.

Поддерживаемые сокращения для ссылок:

[meta] – ссылка на Мету для текущего сайта; текст ссылки должен содержать имя сайта (например «Super User Meta»). Не работает, если у сайта нет Меты (или сайт сам является Метой).

[main] – как [Мета], только наоборот.

[edit] – ссылка на страницу редактирования сообщения, которому адресован комментарий, например /сообщения/<идентификатор>/правка. Текст ссылки «правка» (с учётом регистра).

[tag:tagname] и [meta-tag:tagname] — ссылка на страницу данной метки. Текст ссылки содержит имя метки. meta-tag работает только на Мете

[tour] – ссылка на страницу «Тур». Текст ссылки «тур» (с учётом регистра).

[chat] – ссылка на чат данного сайта, текст ссылки — «Чат <имя сайта>».

[mcve], [mre], [reprex], [repro], [example] – ссылка на страницу /help/minimal-reproducible-example с текстом «минимальный воспроизводимый пример».

[что-то.se] — ссылка на что-то.stackexchange.com, если сайт существует. Текст ссылки содержит имя сайта. Используйте [ubuntu.se] для Ask Ubuntu.

Ответы в комментариях

Автор сообщения всегда получает уведомление о вашем комментарии. Если вы отвечаете другому комментатору, укажите его имя там же: @ peter и @ PeterSmith уведомят предыдущего комментатора по имени “Peter Smith”.

Можно использовать данный метод для отправки уведомления любому редактору сообщения или, при необходимости, ♦ модератору, закрывшему вопрос.

Источник

Шпаргалка по markdown

Заголовки

H1-H2 добавляются в навигацию слева. H1-H6 можно добавить в содержание статьи (см. ниже)

Начертание

Курсив обозначается одинарнимы звездочками или подчеркиваниями.

Полужирный текст обозначаается двойными звёздочками или подчеркиваниями.

Для нужно начертания можно комбинировать звёздочки и подчеркивания.

Две тильды перечёркивают текст.

Списки

Пример текста, который должен быть выровнен по элементу №4

Ссылки

Есть 2 способа создать ссылку

Также любая ссылка, обрамлённая в угловые скобки, автоматом преобразуется
https://www.google.com

Какой-то текст перед сносками

Изображения

Задаются почти также, как и ссылки (2 способа)

Задание ссылки на изображения сразу:

Указание ссылки на изображение в сноске:

Подсветка кода и выделение элементов

Таблицы

Обязательно требуют заголовок и настройки выравнивания (второй строкой). Выравнивание задаётся двоеточием. Колонки задаются вертикальным палками (|)

Внешние вертикальные палки (|) задавать необзяательно, также не требуется подгонять колонки под один размер. Можно использовать стили, описанные выше.

Цитаты

Цитаты задаются угловой скобкой.
Это строка является частью цитаты.

Здесь цитата прерывается.

Можно писать много-много текста, и он автоматически всё преобразует в одну цитату. Также можно использовать разилчные начертания в цитате. Красота!

Уведомления

вместо important можно задать любой класс. наша css тема сейчас поддерживает 3 класса: important, danger, notice. Если надо можно добавить свои-переоформить текущие. Я сейчас использую только important

здесь указан класс danger

здесь указан класс notice

Содержание

Собирает все h1-h6 в статье и делает на них ссылки

В любой момент можно вставить кусок html и не париться.

Тег. Внутри тега markdown **игнорируется**.

Источник

Шпаргалка по Markdown

Заметки по команда для написания текста в формате MarkDown

Поиграть с разметкой Markdown можно на демо-странице.

Содержание

Заголовки

Кроме того, заголовки H1 и H2 можно обозначить подчеркиванием:

Alt-H1

Alt-H2

Выделение

Курсив обозначается звездочками или подчеркиванием.

Комбинированное выделение звездочками и подчеркиванием.

Списки

(В данном примере предшествующие и завершающие пробелы обозначены точками: ⋅)

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

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

Ссылки

Ссылки можно размечать двумя способами.

Или можно просто вставить ссылку в квадратные скобки текст ссылки

Произвольный текст, после которого можно указать сами ссылки. Произвольный текст, после которого можно указать сами ссылки. Произвольный текст, после которого можно указать сами ссылки.

(*) Для символов не входящих в ASCII, например кириллицы, текст сноски все-таки регистрозависим (прим. перев.)

Изображения

Вот наш логотип (наведите указатель, чтобы увидеть текст заголовка):

Внутри строки:

В сноске:

Код и подсветка синтаксиса

Блоки кода являются частью функций Markdown, но не подсветка синтаксиса. Однако многие обработчики, например Github или Markdown Here, поддерживают подсветку синтаксиса. Список поддерживаемых языков и способ их указания может различаться. Markdown Here поддерживает десятки языков (и не-языков, например синтаксис diff и заголовки HTTP); полный список и способ указания языков см. на странице highlight.js demo-странице.

Таблицы

Вертикальные линии обозначают столбцы.

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

Цитаты

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

Встроенный HTML

Часто Markdown понимает чистый HTML.

Список определений Это то, что люди иногда используют. Markdown внутри HTML Работает *не очень** хорошо. Используйте HTML-теги.

Горизонтальные линии

Новая строка

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

Попробуйте ввести следующее:

Это начальная строка

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

Это тоже отдельный абзац, но. [здесь два пробела]
Эта строка отделена одной новой строкой, поэтому она находится в том же абзаце.

(Примечание: В Markdown Here разрывы строк ведут себя так же, как в GFM, поэтому не нужно вставлять по две новые строки.)

Видео Youtube

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

На чистом Markdown, но без размеров изображения и рамки:

Источник