Markdown – это простой, интуитивно понятный и легкий в использовании язык разметки. Он позволяет добавлять форматирование к тексту с помощью символов и синтаксиса. Markdown используется для написания документации, README файлов, блогов, форумов и т.д. так как он позволяет быстро и удобно создавать структурированный текст. Markdown позволяет использовать HTML внутри документа, что расширяет его возможности оформления за счет HTML- тегов.
Наш выбор редактора для базы знаний пал на Markdown.
В нижеприведенных примерах, приложены скриншоты из файлов в формате Markdown.
Заголовки
Для оформления заголовков используется символ #. В зависимости от количества знаков заголовок получает определенный уровень. Выглядит это так:
# Для оформления заголовка первого уровня
## Для оформления заголовка второго уровня
### Для оформления заголовка третьего уровня
#### Для оформления заголовка четвертого уровня
##### Для оформления заголовка пятого уровня
###### Для оформления заголовка шестого уровня
Параграфы и переносы строк
Для оформления параграфа нужно вставить пустую строку между строками текста.
Для переноса, нужно в конце строки добавить два пробела. Некоторые IDE убирают пробелы в конце строк, в таких случаях нужно использовать HTML- тег <br>.
Выделение текста
Для выделения различных частей текста с помощью выделения (курсив, жирный текст, зачеркнутый) используйте следующие символы и способы.
*курсив*
_курсив_
**жирный**
__жирный__
***жирный курсив***
___жирный курсив___
~~зачеркнутый~~
Списки
Сформировать нумерованный список можно следующим способом:
1. Первый элемент списка
2. Второй элемент списка
3. Третий элемент списка
Если нужно сделать маркированный список используйте символы
- Первый элемент списка
- Второй элемент списка
- Третий элемент списка
Вложенные списки
Для отделения подпунктов используются 4 пробела
1. Первый элемент списка
- Подпункт первый
- Подпункт второй
2. Второй элемент списка
- Подпункт первый
- Подпункт второй
Использование ссылок
[Текст ссылки](https://www.example.com)
Вставка изображений
Оформление строки кода
Для выделения строки кода следует заключить его в символы `строка кода`
`Оформление строки кода`
Оформление блока кода
Чтобы оформить блок кода, его нужно заключить в символы ``` блок кода ```
```
Оформление
блока
кода
```
Подсветка кода
Для оформления подсветки кода программы, следует заключить между символами ``` с указанием языка программирования.
```python
print("Привет, мир!")
```
Список поддерживаемых языков программирования впечатляет. Вот только некоторые из них:
Оформление цитат
Оформить цитату можно символом >
> Первый уровень цитирования
>> Второй уровень цитирования
>>> Третий уровень цитирования
Горизонтальная линия
Для разделения текста горизонтальной линией используются символы --- или *** , также можно использовать HTML- тег <hr>
Какой- то текст
***
Еще какой- то текст
Таблицы
| Заголовок 1 | Заголовок 2 |
| ----------- | ----------- |
| Ячейка 1 | Ячейка 2 |
| Ячейка 3 | Ячейка 4 |
Таблица HTML
<table>
<tr>
<th>Заголовок 1</th>
<th>Заголовок 2</th>
</tr>
<tr>
<td>Ячейка 1.1</td>
<td>Ячейка 2.1</td>
</tr>
<tr>
<td>Ячейка 1.2</td>
<td>Ячейка 2.2</td>
</tr>
</table>
Чек- боксы
- [x] Пункт 1
- [ ] Пункт 2
- [ ] Пункт 3
Автоматические ссылки
<http://example.com> <address@example.com>
Использование HTML в Markdown
Как говорилось ранее, Markdown позволяет использовать HTML. Например, Markdown не позволяет объединить ячейки при построении таблицы, а иногда ситуация этого требует. Мы можем для этого использовать возможности HTML.
<table>
<tr>
<th>№ п/п</th>
<th>Наименование</th>
<th>Ед. изм.</th>
<th>Количество</th>
<th>Цена за ед. изм., руб.</th>
<th>Стоимость, руб.</th>
</tr>
<tr>
<td>1.</td>
<td>Кирпич белый</td>
<td>шт</td>
<td>30</td>
<td>69,00</td>
<td>2070</td>
</tr>
<tr>
<td>2.</td>
<td>Кирпич красный</td>
<td>шт</td>
<td>35</td>
<td>48,00</td>
<td>1680</td>
</tr>
<tr>
<td colspan="5" style="text-align:right">ИТОГО:
</td>
<td>1168,80</td>
<!-- Задаем количество ячеек по горизонтали
для объединения-->
</tr>
</table>
Так же, Вы можете использовать HTML- коды.
A¯
Или можно создать с помощью HTML раскрывающуюся подсказку.
<details>
<summary>Markdown</summary>
Markdown- интуитивно понятный, для пользователя,
язык разметки документа.
</details>
Добавление комментария
Добавление комментариев, признак хорошего тона при написании кода программ, Markdown предоставляет возможность добавления комментариев в документ, который будет виден только в режиме редактирования.
Какой- то текст. [//]:
# (Комментарий не будет отображаться в документе)
Еще какой- т текст.
Использование эмодзи
Markdown позволяет встраивать в текст эмодзи
:laughing:
:smile:
:blush:
Что делать, если документация есть, но хранится в файлах формата word или других. На помощь могут прийти онлайн конвертеры. Их много и каждый имеет свои сильные и слабые стороны, но при работе с ними всегда нужно осматривать документ, правильно ли он отображается. Так, например, работая с одним из конвертеров (имен называть не будем) мы увидели, что изображения из документа были вынесены в отдельные файлы, что само по себе правильно, но наименования этих файлов содержало несколько точек, что напрямую влияло на восприятие их базой знаний. После удаления лишних точек из наименования и корректировки ссылок на файлы, проблема была решена.