Уценка на примере

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

Перейти к

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

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

Что такое Markdown

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

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

Джон Грубер создал синтаксис Markdown вместе с Аароном Шварцем в 2004 году как способ «писать, используя простой для чтения и записи простой текстовый формат, и при необходимости преобразовывать его в структурно допустимый XHTML (или HTML)».

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

Примеры синтаксиса Markdown

Примеры будут разбиты на два разных раздела, блочные элементы и элементы пролета. Блочные элементы - это те, которые занимают отдельную строку, например абзацы, код или заголовки.

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

Блочные элементы

Абзацы и новые строки

Создание абзацев и новых строк (или разрывов строк) похоже, но имеет небольшие различия. Новый элемент абзаца <p>...</p> создается каждый раз, когда между двумя строками текста есть пустая строка. Как это:

Уценка:

 Hello, this is a paragraph. 
 
 OMG, this is a new paragraph, you guys. 

HTML:

 <p>Hello, this is a paragraph.</p> 
 <p>OMG, this is a new paragraph, you guys.</p> 

С другой стороны, разрыв строки <br /> вставляется, когда есть новая строка и нет пустой строки, разделяющей текст, например:

Уценка:

 The paragraph starts here... 
 ...and doesn't end until here. 

HTML:

 <p>The paragraph starts here...<br /> 
 ...and doesn't end until here.</p> 
Заголовки

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

Для объявления заголовков H1 или H2 в формате Setext вы можете использовать подчеркивание:

 An H1 Header 
 ============ 
 
 An H2 Header 
 ------------ 

Имейте в виду, что количество используемых вами знаков «=» или «-» не имеет значения. Даже размещение только одного из этих символов под текстом укажет Markdown создать заголовок.

Что касается метода atx, все, что вам нужно сделать, это поставить знаки решетки ( # ) перед текстом. Количество используемых вами знаков решетки определяет используемый тег заголовка (до h6 ).

 # An H1 Header 
 ## An H2 Header 
 ### An H3 Header 
 #### An H4 Header 

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

 # An H1 Header # 
 ## Still an H2 Header #### 
 ### An H3 Header 
Цитаты

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

Первый вариант - добавить к каждой строке цитаты префикс «больше» ( > ).

Уценка:

 > Of all the things I've lost 
 > I miss my mind the most. - Mark Twain 

HTML:

 <blockquote> 
 <p>Of all the things I've lost I miss my mind the most. - Mark Twain</p> 
 </blockquote> 

Это может быть немного утомительно для длинных блоков непрерывного текста, поэтому вместо этого вы можете просто использовать один > перед первой строкой каждого абзаца, а остальные последуют:

Уценка:

 > Measuring programming progress by lines of code is like measuring aircraft building progress by weight. — Bill Gates 

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

Списки

В Markdown поддерживаются оба типа списков HTML - неупорядоченные списки ( <ul> ) и упорядоченные списки ( <ol> ).

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

Маркдодун:

 * Item 1 
 * Item 2 
 * Item 3 
 
 + Item 1 
 + Item 2 
 + Item 3 
 
 - Item 1 
 - Item 2 
 - Item 3 

HTML:

 <ul> 
 <li>Item 1</li> 
 <li>Item 2</li> 
 <li>Item 3</li> 
 </ul> 

Вы даже можете объявить вложенные списки, просто сделав отступ для элемента.

Уценка:

 - Item 1 
 - Sub-item 1 
 - Sub-item 2 
 - Item 2 
 - Sub-item 1 

HTML:

 <ul> 
 <li>Item 1 
 <ul> 
 <li>Sub-item 1</li> 
 <li>Sub-item 2</li> 
 </ul> 
 </li> 
 <li>Item 2 
 <ul> 
 <li>Sub-item 1</li> 
 </ul> 
 </li> 
 </ul> 

Что касается упорядоченных списков, вы объявляете их аналогичным образом, с самой большой разницей в том, что вы используете числа вместо символов * , + или -

Уценка:

 1. Item 1 
 2. Item 2 
 3. Item 3 

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

Уценка:

 45. Item 1 
 0. Item 2 
 910. Item 3 

HTML:

 <ol> 
 <li>Item 1</li> 
 <li>Item 2</li> 
 <li>Item 3</li> 
 </ol> 

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

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

 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean fringilla velit sit amet lectus tincidunt, quis suscipit tortor maximus. Vestibulum facilisis sit amet tortor sed vestibulum. 
 
 Sed nec egestas leo. Nam tristique tincidunt venenatis. Vestibulum vel justo tincidunt, aliquet sapien vitae, vestibulum ex. 
 
 Donec commodo, nunc in posuere condimentum, diam est gravida ex, quis varius nisi neque et nunc. 
 * Nulla facilisi. Mauris eleifend felis a purus pretium egestas 

HTML:

 <ul> 
 <li><p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean fringilla velit sit amet lectus tincidunt, quis suscipit tortor maximus. Vestibulum facilisis sit amet tortor sed vestibulum.</p> 
 
 <p>Sed nec egestas leo. Nam tristique tincidunt venenatis. Vestibulum vel justo tincidunt, aliquet sapien vitae, vestibulum ex.</p> 
 
 <p>Donec commodo, nunc in posuere condimentum, diam est gravida ex, quis varius nisi neque et nunc.</p> 
 <li><p>Nulla facilisi. Mauris eleifend felis a purus pretium egestas</p> 
 </ul> 
Блоки кода

Чтобы показать код в вашем контенте, вы обычно используете pre и code HTML. В Markdown, чтобы добавить блок кода, вам просто нужно сделать отступ для каждой строки либо на 4 пробела, либо на одну табуляцию. Однако это не похоже на абзац, в котором вам нужно сделать отступ только для первой строки, а остальная часть будет следовать. С блоками кода вам действительно нужно делать отступ для каждой строки, чтобы включить ее в блок. Если между кодом есть строки без отступа, они разбивают его на отдельные блоки.

 Check out this code: 
 
 def fibonacci(number): 
 if number <= 1: 
 return number 
 else: 
 return fibonacci(number - 1) + fibonacci(number - 2) 
 
 And use the function like this: 
 
 fib_number = fibonacci(8) 
 print 'The 8th Fibonacci number is:', fib_number 
 
 Wow, that was amazing... 

В некоторых конвертерах Markdown вы также можете использовать три обратных апострофа ( ` ) для создания блоков кода. Лично я предпочитаю этот метод больше, чем отступ, так как его легче читать и писать. Кроме того, если у вас есть подсветка синтаксиса, вы можете объявить, на каком языке находится ваш код, чтобы он знал, как выделить код.

 ```python 
 name = 'Scott' 
 print 'Hi my name is ' + name 
 ``` 

Вам не нужно включать туда «python», но это помогает подсветке синтаксиса быть более точной. Он делает это, добавляя объявленный язык как класс. Таким образом, приведенное выше приведет к следующему:

HTML:

 <pre><code class="language-python"> 
 name = 'Scott' 
 print 'Hi my name is ' + name 
 </code></pre> 
Горизонтальное правило

Чтобы разбить разделы в тексте, вы можете добавить горизонтальные правила ( <hr /> ), которые представляют собой просто длинные строки, охватывающие длину блока, в котором он находится. Чтобы добавить один с Markdown, просто добавьте три или более * или - .

 *** 
 
 or 
 
 --- 

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

 * * * * * 
 
 - - - - - - - - 

Элементы диапазона

Существует несколько различных способов создания ссылок, каждый из которых зависит от необходимых вам метаданных, организации и личных предпочтений. Первый и самый простой способ создать ссылку - использовать следующий формат: [ANCHOR-TEXT](LINK) . Примером может быть:

Уценка:

 [Stack Abuse](http://stackabuse.com) 

HTML:

 <a href="http://stackabuse.com">Stack Abuse</a> 

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

 [Stack Abuse](http://stackabuse.com "Stack Abuse Title") 

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

 OMG it is sooo fun to link to [Stack Abuse][SA], you guys. 
 
 [SA]: http://stackabuse.com "Stack Abuse Link Title" 

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

Акцент

Одним из наиболее часто используемых элементов HTML является выделение текста, например полужирный или курсив. Любой из этих элементов может быть создан с помощью подчеркивания ( _ ) или звездочки ( * ).

Чтобы добавить <em> , используйте одиночный знак _ или * с каждой стороны текста. А для <strong> используйте по два таких символа с каждой стороны. Вот несколько примеров:

Уценка:

 _This is emphasized text!_ 
 
 __This is strong text!__ 
 
 *This is emphasized text!* 
 
 **This is strong text!** 

HTML:

 <em>This is emphasized text!</em> 
 
 <strong>This is strong text!</strong> 
 
 <em>This is emphasized text!</em> 
 
 <strong>This is strong text!</strong> 
Встроенный код

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

Уценка:

 In JavaScript, use `console.log()` to print to the console. 

HTML:

 <p>In JavaScript, use <code>console.log()</code> to print to the console.</p> 

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

Уценка:

 A backtick `` ` `` is used for code blocks. 

HTML:

 <p>A backtick <code>`</code> is used for code blocks.</p> 
Изображений

Создание ссылок на изображения во многом похоже на добавление URL-ссылок. Небольшая разница в том, что вы должны поставить перед ним восклицательный знак ( ! ).

Уценка:

 ![My Alt Text](/path/to/my/pic.jpg "My Optional Title Text") 

HTML:

 <img alt="My Alt Text" title="My Optional Title Text" src="/path/to/my/pic.jpg"> 

И то же самое с URL-ссылками, вы также можете использовать ссылки.

 ![My Alt Text][id] 
 
 [id]: /path/to/my/pic.jpg "My Optional Title Text" 

Разное.

Побег

Если вам когда-нибудь понадобится использовать зарезервированные символы, такие как * , # или _ , вам нужно будет экранировать его с помощью обратной косой черты. Тем не менее, вам нужно только экранировать, если используемый зарезервированный символ находится в формате синтаксиса Markdown.

Уценка:

 OMG \_this\_ had better not have emphasis... 

HTML:

 <p>OMG _this_ had better not have emphasis...</p> 

Следующие символы могут быть экранированы обратной косой чертой:

  • \ (обратная косая черта)
  • `(обратная кавычка)
  • * (звездочка)
  • _ (нижнее подчеркивание)
  • {} (фигурные скобки)
  • [] (квадратных скобках)
  • () (круглые скобки)
  • # (знак решетки)
  • + (знак плюса)
  • - (дефис)
  • . (точка)
  • ! (восклицательный знак)
Автоматическое связывание

Вам доступна сокращенная форма ссылки, но за счет якорного текста. Если вы хотите добавить ссылку и просто указать URL-адрес в качестве якорного текста, вы можете использовать это:

Уценка:

 <http://stackabuse.com> 

HTML:

 <a href="http://stackabuse.com">http://stackabuse.com</a> 
Связывание писем

Примечание. Хотя это заявлено в спецификации Markdown, эта функция поддерживается не всеми конвертерами.

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

Уценка:

 < [email protected] > 

HTML:

 <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a> 

Заключение

Не забывайте, что Markdown также позволяет вставлять простой HTML. Поэтому, если синтаксис не позволяет указать нужные атрибуты, например height и width изображения, то вместо этого можно просто использовать HTML. Отсюда большая сила - в форме гибкости.

Обратите внимание, что это не исчерпывающее руководство по синтаксису Markdown. Если вам нужен более полный и исчерпывающий ресурс, вам следует либо обратиться к конкретному конвертеру, который вы используете, либо к руководству Джона Грубера на Daring Fireball .

comments powered by Disqus