Лекц/MarkDownHTML.html

<!DOCTYPE html>
<html>
  <head>
    <title>Title</title>
    <meta charset="utf-8">
    <style>
      @import url(https://fonts.googleapis.com/css?family=Yanone+Kaffeesatz);
      @import url(https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic);
      @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic);

      body { font-family: 'Droid Serif'; }
      h1, h2, h3 {
        font-family: 'Yanone Kaffeesatz';
        font-weight: normal;
      }
      .remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; }
    </style>
  </head>
  <body>
    <textarea id="source">

class: center, middle

**Програмна інженерія в системах управління.**

# Створення документації на основі MarkDown

Мова MarkDown (MD). Редактори. 

---

## MarkDown (MD). 

* DOC чи DOCX зберігають документи не в текстовому форматі	
    * що ускладнює їх відображення в онлайні
    * ускладнює керування версіями. 
* Альтернативою є  мова Markdown, 
    * дозволяє відображати форматовані тексти на сторінках 
    * використовувати мультикористувацькі функції.
    * використовується в GitHub для відображення текстового змісту репозиторіїв.      

**«Markdown»** (створена John Gruber’s)  — полегшена [мова розмітки даних](https://uk.wikipedia.org/wiki/Мова_розмітки_даних), яку створено з ухилом на [прочитність](https://uk.wikipedia.org/wiki/Прочитність) та зручність у публікації з подальшим перетворенням її на структуровану валідність  [XHTML](https://uk.wikipedia.org/wiki/XHTML) або [HTML](https://uk.wikipedia.org/wiki/HTML).

У багатьох  випадках можуть використовуватися додаткові елементи синтаксису, які відрізняються від використовуваного переглядача. Опис доступний також на сайті https://www.markdownguide.org/ 

---

## Версійність MD. 

Кожен застосунок реалізує дещо іншу версію Markdown - ***аромати(Flavors)***, аналогічно як діалекти в мовах. 

Для перевірки роботи прикладів -  https://dillinger.io/

---

## Загальні принципи функціонування

Тексти Markdown зберігаються у текстовому файлі з розширенням `.md` або` .markdown`.
Для відображення необхідний *застосунок Markdown*. Усі програми роблять одне і те саме - перетворюють текст Markdown у HTML. Для цих цілей застосунки Markdown використовують ***Markdown-обробники***  («парсери» ). 

![MD Processor](MdMedia/process.png "Обробка тексту MarkDown")

---

## Екранування

Для форматування в MD використовуються спеціалізовані літери. Для того щоб ці літери, які Markdown однозначно визначає як команди форматування, могли бути відображені як звичайні, вони можуть бути екрановані зворотною косою лінією; наприклад, вираз 

```markdown
'\*'
```

виведе зірочку (*), а не означатиме початок проміжку виділеного тексту. 

---

## Заголовки

HTML-заголовки створюються розміщенням тої кількості "решіток" перед текстом заголовка, що  відповідає бажаному рівню (HTML підтримує 6 рівнів заголовків),  наприклад:

```markdown
 # це заголовок першого рівня
 #### це заголовок четвертого рівня
```

Це матиме наступний вигляд:

![Рисунок 1](MdMedia/Рисунок1.png)

Перші два рівні заголовків також мають альтернативний синтаксис:

```markdown
Заголовок першого рівня
=======================

Заголовок другого рівня
-----------------------
```

---

## Параграфи

розділяються  одним чи декількома порожніми рядками

```markdown
Це параграф. Він містить два речення.

Це інший параграф. Він також містить два речення.
```

---

## Список

Починаютья з `* `,  `+ `, або  `- `, кожен підпункт виділяється чотирма пробілами 

```markdown
 * Пункт в маркованому (ненумерованому) списку
     * Підпункт, відділений 4 пробілами
         * підпункт третього рівня, виділений 4 пробілами
 * Інший пункт в маркованому списку

 1. Пункт в нумерованому списку
     1.1. Підпункт, відділений 4 пробілами
 2. Інший пункт в нумерованому списку
```

Це матиме наступний вигляд

![Рисунок 2](MdMedia/Рисунок2.png "Рисунок 2")

---

## Формат тексту

```markdown
 *emphasis* або _emphasis_ (тобто нахил)

 **сильне виділення** або __сильне виділення__ (тобто напівжирний)
```

```markdown
це ~~закреслений текст~~
```

---

## Код

Для включення коду (відформатованого в моноширинний шрифт), ви можете або оточити вбудований код зворотніми лапками (`` `), наприклад, \`деякий код\`, або відділити декілька рядків коду щонайменше чотирма пробілами, як тут:

```markdown
    перший рядок коду
    другий рядок коду
    третій рядок коду
```

Останній варіант за допомогою пробілів дозволяє зберігати і показувати синтаксис Markdown.

---

## Кінець рядку

Якщо необхідно вставити закінчення рядка Markdown (символ `<BR>` в HTML), треба в кінці рядку вставити щонайменше два пробіли.

Наприклад:

```markdown
 def show_results space space
 end
```

---

## Цитати

Цитати позначаються символом `>`

```markdown
 > Весь цей абзац тексту буде поміщений у HTML blockquote елемент.
 Blockquote елементи змінюються в залежності від потреби/пристрою виводу.
 Ви можете обернути довільний текст за власним смаком, та воно перетвориться
 на єдиний blockquote елемент.
```

Приклад вище перетвориться на такий HTML:

```html
<blockquote><p>Весь цей абзац тексту буде поміщений у HTML blockquote елемент.
 Blockquote елементи змінюються в залежності від потреби/пристрою виводу.
 Ви можете обернути довільний текст за власним смаком, та воно перетвориться
 на єдиний blockquote елемент.</p></blockquote>
```

Якщо необхідно цитату зробити в кілька рядків, кожен рядок починається з символу `>` Вкладеність цитат досягається подвійним символом  `>>`

---

## Зовнішні посилання

Посилання можуть бути вбудованими:

```markdown
[текст посилання](адреса посилання)
```

Наприклад: `[Markdown](http://en.wikipedia.com/wiki/Markdown)` матиме вигляд

[Markdown](http://en.wikipedia.com/wiki/Markdown)

Також посилання можуть бути розміщені у примітках поза параграфом. Наприклад, наступний формат тексту

```markdown
[текст посилання][1]
```

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

```markdown
 [1]: http://en.wikipedia.com/wiki/Markdown "Markdown на WiKi"
```

---

## Зображення

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

```markdown
![Альтернативний текст](/path_to/img.jpg)
```

або:

```markdown
![Альтернативний текст](/path_to/img.jpg "Це текст до рисунку")
```

Як і посилання, зображення також можуть мати стиль синтаксису примітки, 

```markdown
![Альтернативний текст][id]
```

з пізнім посиланням в документі, яке визначає URL розміщення зображення.

```markdown
 [id]: url/to/image "Optional title attribute"
```

---

## Горизонтальні лінії

Горизонтальні лінії задаються розміщенням трьох або більшим дефісів, зірочок, або  підкресленням в рядку самостійно. Ви можете використовувати пробіли між  дефісами чи зірочками. Кожен з наведених нижче рядків створить  горизонтальну лінію:

```markdown
 * * *
 ***
 *****
 - - -
 ---------------------------------------
```

---

## HTML

Деякі переглядачі дозволяють використовувати пряме вставлення тегів HTML. Але з точки зору безпеки не усі Markdown  застосунки підтримують HTML в документах Markdown. Деякі ж підтримують тільки деякі з тегів.  Необхідно використовувати пусті лінії для відділення блочних елементів HTML такі як `<div>`, `<table>`, `<pre>`, та `<p>` від їх контенту. 

---

## Використання 

- #### Websites

- #### Документи

- #### Нотатки

- #### Книги

- #### Presentations

- #### Email

- #### Технічна документація

---

## Редактори

Хоча Markdown є полегшеною мовою розмітки яку легко читати та редагувати  звичайними текстовими редакторами, існують спеціально розроблені  редактори, які дозволяють попередньо переглядати зі стилями. Є безліч  таких редакторів, які наявні для всіх основних платформ. Існує плаґін [підсвітки синтаксису](https://uk.wikipedia.org/wiki/Підсвітка_синтаксису) для Markdown, вбудований у [gedit](https://uk.wikipedia.org/wiki/Gedit) та [Vim](https://uk.wikipedia.org/wiki/Vim).

Деякі з редакторів:

- **Mac:** [MacDown](https://www.markdownguide.org/tools/macdown/), [iA Writer](https://www.markdownguide.org/tools/ia-writer/), або[Marked](https://marked2app.com/)
- **iOS / Android:** [iA Writer](https://www.markdownguide.org/tools/ia-writer/)
- **Windows:** [ghostwriter](https://wereturtle.github.io/ghostwriter/) або [Markdown Monster](https://markdownmonster.west-wind.com/)
- **Linux:** [ReText](https://github.com/retext-project/retext) або [ghostwriter](https://wereturtle.github.io/ghostwriter/)
- **Web:** [Dillinger](https://www.markdownguide.org/tools/dillinger/) або [StackEdit](https://www.markdownguide.org/tools/stackedit/)

Крім наведених вище є набагато більше платних та безкоштовних редакторів. Наприклад [Typora](https://typora.io/)   - це редактор Markdown що працює за принципом *Live Preview*, тобто після введення редагування тексту, він одразу показує результат. Підтримує багато мов локалізації, у тому числі українську. Завантажується [за посиланням](https://typora.io/#download). Наразі знаходиться в режимі бета-тестування, тому є безкоштовним. Typora використовує аромат Markdown сумісний з GitHub.    

---

## Розширений синтаксис

Існує кілька легких мов розмітки, які є *супер-наборами* у Markdown. Вони включають основний синтаксис Грубера та надбудовують його, додаючи додаткові елементи, такі як таблиці, кодові блоки, підсвічування синтаксису, автоматичне посилання URL-адрес та виноски. У багатьох найпопулярніших додатках Markdown використовується одна з таких легких мов розмітки:

- [CommonMark](https://commonmark.org)
- [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/)
- [Markdown Extra](https://michelf.ca/projects/php-markdown/extra/)
- [MultiMarkdown](https://fletcherpenney.net/multimarkdown/)
- [R Markdown](https://rmarkdown.rstudio.com/)

---

## Таблиці

Щоб додати таблицю, використовуйте три чи більше дефісів (`---`), щоб створити заголовок кожного стовпця, а для розділення кожного стовпця використовуйте труби (` | `). Ви можете додатково додати труби на будь-якому кінці таблиці.

```markdown
| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |
```

Результат матиме наступний вигляд:

| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

Ширина комірок може змінюватися, як показано нижче. Але результат матиме однаковий вигляд.

```markdown
| Syntax | Description |
| --- | ----------- |
| Header | Title |
| Paragraph | Text |
```

---

### Таблиці: вирівнювання

Ви можете вирівняти текст у стовпцях ліворуч, праворуч або по центру, додавши двокрапку (`:`) зліва, справа або з обох боків дефісів у рядку заголовка.

```
| Syntax      | Description | Test Text     |
| :---        |    :----:   |          ---: |
| Header      | Title       | Here's this   |
| Paragraph   | Text        | And more      |
```

Це матиме наступний вигляд:

| Syntax    | Description |   Test Text |
| :-------- | :---------: | ----------: |
| Header    |    Title    | Here’s this |
| Paragraph |    Text     |    And more |

Ви можете відформатувати текст у таблицях. Наприклад, ви можете додати посилання, код, і форматування. Але ви не можете додавати заголовки, блоки цитат, списки, горизонтальні правила, зображення чи теги HTML.

---

## Огороджені блоки коду 

Основний синтаксис Markdown дозволяє створити кодові блоки шляхом відступу рядків на чотири пробіли або одну вкладку. Якщо вам це незручно, спробуйте використовувати огороджені кодові блоки. Залежно від процесора або редактора Markdown, ви будете використовувати три зворотні одинарні лапки ```` `або три тилди (` ~~~ `) на рядках до і після кодового блоку. Не потрібно відступати жодних рядків!

~~~
```
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```
~~~

Зрештою, це матиме вигляд:

```
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

---

### Огороджені блоки коду: підсвічування синтаксису 

Багато процесорів Markdown для огороджених блоків коду підтримують підсвічування синтаксису . Ця функція дозволяє додавати кольорове підсвічування для будь-якої мови, на якій був написаний ваш код. Щоб додати підсвічування синтаксису, вкажіть мову поруч із задніми позначками перед огородженим кодом блоку. Наступний шматок тексту

```
​```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
​```
```

матиме такий вигляд:

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

---

## Виноски

Щоб створити посилання на виноску, додайте каретку та ідентифікатор всередині дужок (`[^1]`). Ідентифікатори можуть бути числами або словами, але вони не можуть містити пробілів чи вкладок. Ідентифікатори лише співвідносять посилання виноски із самим виноском - у висновку виноски нумеруються послідовно.

Додайте виноску, використовуючи іншу каретку та цифру всередині дужок із двокрапкою та текстом (`[^1]: My footnote.`). Не потрібно ставити виноски в кінці документа. Ви можете розмістити їх куди завгодно, крім інших елементів, таких як списки, блокові лапки та таблиці.

```
Here's a simple footnote,[^1] and here's a longer one.[^bignote]  
[^1]: This is the first footnote.
[^bignote]: Here's one with multiple paragraphs and code.
    Indent paragraphs to include them in the footnote.
    `{ my code }`
    Add as many paragraphs as you like.
```

Це матиме вигляд:

![](MdMedia/Рисунок5.png)

---

## Ідентифікатори заголовків (Heading ID)

Багато процесорів Markdown підтримують власні ідентифікатори для [заголовків](https://www.markdownguide.org/basic-syntax/#headings) - деякі процесори Markdown автоматично додають їх. Додавання спеціальних ідентифікаторів дозволяє вам безпосередньо посилатися на заголовки та змінювати їх за допомогою CSS. Щоб додати спеціальний ідентифікатор заголовка, додайте його до фігурних фігурних дужок у тому ж рядку, що й заголовка.

```
#### My Great Heading {#custom-id}
```

HTML матиме наступний вигляд:

```html
<h3 id="custom-id">My Great Heading</h3>
```

---

### Ідентифікатори: зв'язок

Ви можете зв’язати заголовки зі спеціальними ідентифікаторами у файлі, створивши [стандартне посилання](https://www.markdownguide.org/basic-syntax/#links) зі знаком цифри (`#`), за яким слідує ідентифікатор заголовку.

| Markdown                      | HTML                           | Вигляд                                                       |
| ----------------------------- | ------------------------------ | ------------------------------------------------------------ |
| `[Heading IDs](#heading-ids)` | ` [Heading IDs](#heading-ids)` | [Heading IDs](https://www.markdownguide.org/extended-syntax/#heading-ids) |

Інші веб-сайти можуть посилатися на заголовок, додавши спеціальний ідентифікатор заголовка до повної URL-адреси веб-сторінки (наприклад,

`[Heading IDs](https://www.markdownguide.org/extended-syntax#heading-ids)`.

---

## Списки означень

```markdown
First Term
: This is the definition of the first term.
Second Term
: This is one definition of the second term.
: This is another definition of the second term.
```

HTML матиме вигляд:

```html
<dl>
  <dt>First Term</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Second Term</dt>
  <dd>This is one definition of the second term. </dd>
  <dd>This is another definition of the second term.</dd>
</dl>
```

У переглядачі це матиме вигляд:

![](MdMedia/Рисунок3.png)

---

## Список завдань 

Списки завдань дозволяють створити список елементів за допомогою прапорців. У додатках Markdown, що підтримують списки завдань, поруч із вмістом відображатимуться прапорці. Щоб створити список завдань, перед пунктами списку завдань додайте тире (`-`) і дужки з пробілом (` [ ] `). Щоб встановити прапорець, додайте між дужками "x" (`[x]`).

```
- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media
```

Це матиме вигляд:

- [x] Write the press release
- [ ] Update the website
- [ ] Contact the media

![](MdMedia/Рисунок4.png)

---

## Емоджи (смайлики)

Деякі програми Markdown дозволяють вставляти смайли, вводячи короткі коди смайлів. Вони починаються і закінчуються двокрапкою і включають назву емоджи.

```markdown
Gone camping! :tent: Be back soon.
That is so funny! :joy:
```

Матиме вигляд:

Gone camping! ⛺ Be back soon.

That is so funny! 😂

Ви можете використовувати цей [список коротких кодів емоджі](https://gist.github.com/rxaviers/7360908), але майте на увазі, що короткі коди емоджі відрізняються для різних застосунків. 

---

## Автоматичне зв'язування URL 

Багато процесорів Markdown автоматично перетворюють URL-адреси в посилання. Це означає, що якщо ви введете http://www.example.com, ваш процесор Markdown автоматично перетворить його на посилання, навіть якщо ви не [використали дужки](https://www.markdownguide.org/basic-syntax/ # посилання). Тобто введений текст

```
http://www.example.com
```

автоматично буде сприйматися як лінк:

http://www.example.com

Якщо ви не хочете, щоб URL-адресу було автоматично пов’язано, ви можете видалити посилання, [позначаючи URL-адресу як код](https://www.markdownguide.org/basic-syntax/#code) за допомогою зворотних лапок.

```
`http://www.example.com`
```


   </textarea>
    <script src="https://remarkjs.com/downloads/remark-latest.min.js">
    </script>
    <script>
      var slideshow = remark.create();
    </script>
  </body>
</html>