Browse Source

Обновить 'README.md'

Dmitry Shin 9 years ago
parent
commit
402a3f1d36
1 changed files with 380 additions and 1 deletions
  1. 380 1
      README.md

+ 380 - 1
README.md

@@ -1,2 +1,381 @@
-# markdown-doc
+Настоящий документ предназначен для ознакомления пользователя с функциональными возможностями языка разметки Markdown. 
+Markdown – это облегченный язык разметки, который является инструментом преобразования кода в HTML.
+Главной особенностью данного языка является максимально простой синтаксис, который служит для упрощения написания и чтения кода разметки, что, в свою очередь, позволяет легко его корректировать.
+Теперь рассмотрим более подробно функции языка разметки Markdown.   
 
 
+Markdown не является заменой HTML. Синтаксис Markdown достаточно ограничен, и соответствует лишь небольшому подмножеству элементов HTML. Он включает в себя следующие элементы:
+
+1. Блочные элементы
+ + [Параграфы и разрывы строк](#Parag);
+ + [Заголовки](#Headers);
+ + [Цитаты](#Blockquotes);
+ + [Списки](#Lists)
+ + [Блоки кода](#CodeBlocks);
+ + [Горизонтальные (разделительные) линии](#Lines).
+2. Строчные элементы
+ + [Ссылки](#Links);
+ + [Выделение текста](#Emphasis);
+ + [Кодовые фрагменты строк](#Code);
+ + [Изображения](#Images).
+3. Дополнительные элементы
+ + [Обратный слеш](#Backslash Escapes);
+ + [Автоматические ссылки](#Automatic Links);
+ + [Специальные символы HTML](#SpecialSymbol).  
+
+Более подробно с перечисленными функциями можно ознакомиться в разделе «Описание синтаксиса».
+
+ОПИСАНИЕ СИНТАКСИСА
+=========================
+   
+Блочные элементы
+--------------------------  
+
+##### <a name="Parag"></a>	Параграфы и разрывы строк
+Для того, чтобы создать параграф с использованием синтаксиса языка Markdown, достаточно отделить строки текста одной (или более) пустой строкой (пустой считается всякая строка, которая не содержит в себе ничего, кроме пробелов и символов табуляции).
+Для того, чтобы вставить видимый перенос строки (элемент `<br/>`) необходимо окончить строку двумя пробелами и нажатием клавиши «Enter». 
+Многие элементы синтаксиса Markdown выглядят и работают гораздо лучше в случае, когда их форматируют с помощью «жесткого перевода строк» (разделение строк, осуществленное самим пользователем, а не программой автоматически). К таким элементам относятся цитаты, списки и пр.  
+
+##### <a name="Headers"></a> Заголовки  
+Язык разметки Markdown поддерживает 2 стиля обозначения заголовков: подчеркивание и выделение символом («#»).
+Выделение заголовков с помощью подчеркивания производится знаками равенства («=») в случае, если заголовок первого уровня, и дефисами («-») в случае, если заголовок второго уровня. Количество знаков подчеркивания не ограничивается.
+При выделении заголовков с помощью символа («#») используется от одного до шести данных символов, которые устанавливаются в начале строки (перед заголовком). В данном случае количество символов соответствует уровню заголовка. Кроме того, заголовок возможно снабдить закрывающимися символами («#»), хотя это и не является обязательным. Количество закрывающихся символов не обязано соответствовать количеству начальных символов. Уровень заголовка определяется по количеству начальных символов.  
+Заголовки первого и второго уровней, выполненные с помощью подчеркивания, выглядят следующим образом:
+
+    Заголовок первого уровня
+    ========================
+    Заголовок второго уровня
+    -------------------------
+
+Заголовки первого, третьего и шестого уровней, выполненные с помощью символа («#»), выглядят следующим образом:
+	
+    #  Заголовок первого уровня
+    ### Заголовок третьего уровня
+    ###### Заголовок шестого уровня
+Приведенные выше заголовки, выполненные с помощью символа («#») тождественны следующим:
+
+    #  Заголовок первого уровня #
+    ### Заголовок третьего уровня ###
+    ###### Заголовок шестого уровня ######
+В результате на экран выводится следующее:
+
+Заголовок первого уровня
+========================
+
+Заголовок второго уровня
+------------------------
+
+#  Заголовок первого уровня
+### Заголовок третьего уровня
+###### Заголовок шестого уровня
+
+##### <a name="Blockquotes"></a> 	Цитаты  
+Для обозначения цитат в языке Markdown используется знак «больше» («>»). Его можно вставлять как перед каждой строкой цитаты, так и только перед первой строкой параграфа. 
+Также синтаксис Markdown позволяет создавать вложенные цитаты (цитаты внутри цитат). Для их разметки используются дополнительные уровни знаков цитирования («>»).
+Цитаты в Markdown могут содержать всевозможные элементы разметки.
+Цитаты в языке Markdown выглядят следующим образом:
+
+    >Это пример цитаты,
+    >в которой перед каждой строкой
+    >ставится угловая скобка.
+
+    >Это пример цитаты,
+    в которой угловая скобка
+    ставится только перед началом нового параграфа.
+    >Второй параграф.
+
+Вложение цитаты в цитату выглядит следующим образом:
+
+    > Первый уровень цитирования
+    >> Второй уровень цитирования
+    >>> Третий уровень цитирования
+    >
+    >Первый уровень цитирования
+В результате на экран выводится следующее:
+
+>Это пример цитаты,
+>в которой перед каждой строкой
+>ставится угловая скобка.
+
+>Это пример цитаты,
+в которой угловая скобка
+ставится только перед началом нового параграфа.
+
+>Второй параграф.
+
+Вложенная цитата:
+
+> Первый уровень цитирования
+>> Второй уровень цитирования
+>>> Третий уровень цитирования
+>
+>Первый уровень цитирования
+
+
+Уровень цитирования не может превышать 15-й.  
+
+##### <a name="Lists"></a> Списки
+Markdown поддерживает упорядоченные (нумерованные) и неупорядоченные (ненумерованные) списки.
+ Для формирования неупорядоченный списков используются такие маркеры, как звездочки, плюсы и дефисы. Все перечисленные маркеры могут использоваться взаимозаменяемо. 
+Для формирования упорядоченных списков в качестве маркеров используются числа с точкой. Важной особенностью в данном случае является то, что сами номера, с помощью которых формируется список, не важны, так как они не оказывают влияния на выходной HTML код. Как бы ни нумеровал пользователь список, на выходе он в любом случае будет иметь упорядоченный список, начинающийся с единицы (1, 2, 3…). Эту особенность стоит учитывать в том случае, когда необходимо использовать порядковые номера элементов в списке, чтобы они соответствовали номерам, получающимся в HTML.
+Упорядоченные списки всегда следует начинать с единицы. Маркеры списков обычно начинаются с начала строки, однако они могут быть сдвинуты, но не более чем на 3 пробела. За маркером должен следовать пробел, либо символ табуляции. 
+При  необходимости в список можно вставить цитату. В этом случае обозначения цитирования ( «>» ) нужно писать с отступом.
+Упорядоченные списки выглядят следующим образом:
+
+    1.	Проводник
+    2.	Полупроводник
+    3.	Диэлектрик
+
+Неупорядоченные списки выглядят следующим образом:
+
+    * Проводник
+    * Полупроводник
+    * Диэлектрик
+
+Или
+
+    - Проводник
+    - Полупроводник
+    - Диэлектрик
+
+Или
+
+    + Проводник
+    + Полупроводник
+    + Диэлектрик
+На выходе всех трех перечисленных вариантов имеется один и тот же результат.
+В результате на экран выводится следующее:
+
+1. Проводник
+2. Полупроводник
+3. Диэлектрик
+
+и
+
++ Проводник
++ Полупроводник
++ Диэлектрик
+
+Цитата, вставленная в список, выглядит следующим образом:
+
+    1. Элемент списка с цитатой:
+
+        > Это цитата
+        > внутри элемента списка.
+
+     2. Второй элемент списка
+
+В результате на экран выводится следующее:
+
+1. Элемент списка с цитатой:
+
+    > Это цитата
+    > внутри элемента списка.
+
+2. Второй элемент списка
+
+
+При вставке цитат в элементы списка важно учитывать, что элементы списка должны находиться на одном уровне, а цитаты должны указываться с отступом. В случае, если правило с единым уровнем списка не соблюдается, следующий после цитаты элемент списка будет автоматически нумероваться цифрой «1.». 
+Кроме того, при необходимости в список можно вставить исходный код. В этом случае его нужно писать с двойным отступом – 8 пробелов или 2 символа табуляции. 
+
+ - Элемент списка, содержащий исходный код
+
+		<исходный код >  
+
+##### <a name="CodeBlocks"></a> Блоки кода
+Отформатированные блоки кода используются в случае необходимости процитировать исходный код программ или разметки. 
+Для создания блока кода в языке Markdown необходимо каждую строку параграфа начинать  с отступа, состоящего из четырех пробелов или  одного символа табуляции. Блок кода продолжается до тех пор, пока не встретится строка без отступа (или конец текста).  Внутри блока кода амперсанды («&») и угловые скобки («<» и «>») автоматически преобразуются в элементы HTML разметки. Кроме того, следует отметить, что внутри блоков кода обычный синтаксис Markdown не обрабатывается. 
+Блок кода в Markdown выглядит следующим образом:
+
+Это обычный параграф:
+
+	Это блок кода
+
+##### <a name="Lines">	</a> Горизонтальные линии (разделители)  
+
+Для того чтобы создать горизонтальную линию с использованием синтаксиса языка Markdown, необходимо поместить три (или более)дефиса или звездочки на отдельной строке текста. Между ними возможно располагать пробелы. 
+Горизонтальные линии в Markdown выглядят следующим образом:
+
+    Первая часть текста, который необходимо разделить
+    ***
+    Вторая часть текста, который необходимо разделить
+
+Или
+
+    Первая часть текста, который необходимо разделить
+
+    ---
+
+    Вторая часть текста, который необходимо разделить
+В результате на экран выводится следующее:
+
+Первая часть текста, который необходимо разделить
+***
+Вторая часть текста, который необходимо разделить  
+
+При использовании данного инструмента важно помнить, что после первой части текста и перед второй необходимо оставлять пустую строку. Данное правило необходимо соблюдать только при использовании дефисов. Если его не соблюдать, на экран будет выведен заголовок второго уровня и строка обычного текста.  При использовании символа звездочки данным правилом можно пренебречь.  
+
+ Строчные элементы
+-------------------  
+
+##### <a name="Links"></a> Ссылки
+Markdown поддерживает два стиля оформления ссылок:
+
+ - Гиперссылка, с немедленным указанием адреса (внутритекстовая);
+ - Гиперссылка, подобная сноске.
+
+Подразумевается, что помимо URL-адреса существует еще текст ссылки. Он заключается в квадратные скобки. 
+Для создания внутритекстовой гиперссылки необходимо использовать круглые скобки сразу после закрывающей квадратной. Внутри них необходимо поместить URL-адрес. В них же возможно расположить название, заключенное в кавычки, которое будет отображаться при наведении, но этот пункт не является обязательным. 
+ 
+      [пример](http://example.com/ "Необязательная подсказка")
+В результате на экран выводится следующее:
+[пример](http://example.com/ "Необязательная подсказка")
+При ссылке на локальную директорию возможно использование относительного пути (от текущей страницы, сайта и т.п.)  
+
+При создании сносной гиперссылки вместо целевого адреса используется вторая пара квадратных скобок, внутри которых помещается метка, идентификатор ссылки (id).
+
+    [пример][id]:
+Также, можно использовать пробел, чтобы отделять 2 пары квадратных скобок: 
+
+    [пример] [id]: 
+
+В этом случае возможно определить идентификатор в любом месте документа: 
+
+    [id]: http://example.com/ "Необязательная подсказка"
+
+В результате на экран выводится следующее:
+[пример] [id] 
+[id]: http://example.com/ "Необязательная подсказка"
+Иными словами, она состоит из следующих элементов:
+
+ - Идентификатор ссылки, окружённый квадратными скобками (которым может предшествовать необязательный отступ от одного до трёх пробелов);
+ - 	Двоеточие;
+ - 	Один или несколько пробелов (или символов табуляции);
+ - 	URL гиперссылки;
+ - 	Необязательный заголовок (подсказка к изображению, которая всплывает при наведении на него) гиперссылки, заключённый либо в двойные или одиночные кавычки, либо в скобки.
+
+Идентификаторы ссылок могут состоять из букв, цифр, пробелов и знаков пунктуации, однако они не чувствительны к регистру. То есть эти два варианта эквивалентны:
+
+    [текст ссылки][a]
+    [текст ссылки][A]
+Markdown позволяет также использовать неявно выраженный идентификатор (сокращенный). В этом случае метка не приводится, вместо неё текст гиперссылки используется  и в качестве её имени, а вторая пара квадратных скобок остаётся пустою.
+Например, чтобы сделать слово «Example» гиперссылкой, ведущей на сайт <http://example.com/>, достаточно написать:
+
+    [Example][]
+и затем определить гиперссылку:
+
+    [Example]: http://example.com/
+В результате на экран выводится следующее:
+[Example][]
+[Example]: http://example.com/  
+
+##### <a name="Emphasis"></a> 	Выделение текста
+Markdown воспринимает звёздочки «*» и символы подчёркивания «_» как признаки смыслового выделения текста:
+
+ - Текст, окружённый одиночными «*» или «_», будет заключен в HTML-тэг `<em>`.
+ -  Текст, окружённый двойными «*» или «_», будет заключен в HTML-тэг `<strong>`.
+
+Иными словами, текст, окруженный одинарными символами, выделяется курсивным шрифтом, а текст, окруженный двойными символами, выделяется полужирным шрифтом. 
+Также, выделенный фрагмент может находиться в любой части слова. 
+Текст, выделенный курсивом с использованием синтаксиса языка Markdown, выглядит следующим образом:
+
+    *Пример*  
+*Пример*  
+
+Текст, выделенный полужирным шрифтом с использованием синтаксиса языка Markdown, выглядит следующим образом:
+
+    **Пример**
+**Пример**  
+
+Текст, выделенный курсивным полужирным шрифтом с использованием синтаксиса языка Markdown выглядит следующим образом:
+
+    ***Пример***
+***Пример***
+
+Все приведенные выше примеры аналогичны следующим:
+
+    _Пример_
+
+    __Пример__
+
+    Пере___распред___деление
+
+    ___Пример___  
+
+##### <a name="Code"></a>	Кодовые фрагменты строк
+Чтобы отметить фрагмент строки, содержащий код, необходимо окружить его обратными апострофами «`».  При использовании кодовых фрагментов строк текст будет отображаться в виде моноширинного шрифта. 
+В отличие от блоков кода, кодовый фрагмент позволяет поместить код внутрь обычного абзаца текста.
+Кодовый фрагмент строки в языке Markdown выглядит следующим образом:
+
+Используйте оператор `if`  
+
+##### <a name="Images"></a>	Изображения
+В Markdown существует 2 способа вставки изображений в документ:
+
+a.	С помощью непосредственного указания URL-адреса изображения. Синтаксис данной команды выглядит следующим образом:
+
+    ![Альтернативный текст](/путь/к/изображению.jpg)
+или
+
+    ![Альтернативный текст](/путь/к/изображению.jpg "Подсказка")
+Иными словами, он состоит из следующих элементов:
+
+ - восклицательный знак;
+ -  квадратные скобки, в которых указывается альтернативный изображению текст (он станет содержимым атрибута в элементе img);
+ -  круглые скобки, содержащие URL-адрес или относительный путь изображения, а также (необязательно) всплывающую подсказку, заключённуе в двойные или одиночные кавычки.
+
+b.	С помощью метки-идентификатора.  Синтаксис данной команды записывается следующим образом:
+
+    ![Альтернативный текст][id]
+где «id» — имя определённой метки изображения. Метки изображений определяются при помощи синтаксиса, совершенно идентичного меткам гиперссылок:
+
+    [id]: путь/к/изображению "Необязательная подсказка"
+Важной особенностью является то, что Markdown не позволяет задать размеры изображения (ширину, высоту).  
+
+ Дополнительные элементы
+-------------------------  
+
+##### <a name="Backslash Escapes"></a>	Обратный слеш
+Может употребляться в Markdown перед специальными символами для того, чтобы они воспринимались в их буквальном (а не служебном) значении. Полный список данных символов приводится ниже:
+
+«\»  - слеш;  
+
+«`»  - обратный апостроф;  
+
+«*»  - звездочка;  
+
+«_»  - символ подчеркивания;  
+
+«{}»  - фигурные скобки;  
+
+«[]»  - квадратные скобки;  
+
+«()»  - круглые скобки;  
+
+«#»  - символ решетки;  
+
+«+»  - плюс;  
+
+«-»  - минус (дефис);  
+
+«.»  – точка;  
+
+«!»  - восклицательный знак.  
+
+##### <a name="Automatic Links"></a> Автоматические ссылки
+Markdown поддерживает упрощённый порядок автоматического создания ссылок для URL-адресов и адресов электронной почты. Для этого достаточно поместить URL-адрес или почтовый адрес в угловые скобки, и Markdown сделает его гиперссылкой. В отличие от вышеописанных стилей, в данном случае сам же URL-адрес или почтовый адрес становится и текстом гиперссылки. Автоматические ссылки на адреса электронной почты работают аналогично.
+Автоматические ссылки в языке Markdown выглядят следующим образом
+
+    <http://example.com/>
+В результате на экран выводится следующее:
+<http://example.com/>
+
+Автоматическая ссылка на адрес электронной почты в Markdown выглядит следующим образом
+
+    <address@example.com>
+В результате на экран выводится следующее:
+<address@example.com>  
+
+##### <a name="SpecialSymbol"></a> Специальные символы HTML
+В языке HTML существует два символа, требующих специального рассмотрения: это символы («&lt;») и («&amp;»). Левая угловая скобка используется как начало тэга; амперсанды применяются для обозначения специального символа HTML.
+Для того чтобы использовать эти символы в их буквальном смысле, необходимо заменить их элементами HTML, а именно `&lt;` и `&amp;` соответственно.
+При использовании Markdown подобных действий совершать не нужно. Он позволяет использовать эти символы в исходном виде. В случае если амперсанд используется как часть спецсимвола HTML, он останется неизменным. В противном случае Markdown преобразует его в `&amp;`.