Руководство по оформлению Markdown файлов

Обновлено: 2023-09-01

4 мин

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

Рекомендации по оформления статьи

Заголовки

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

Заголовок первого уровня
========================
Заголовок второго уровня
-------------------------

Заголовок первого уровня

Заголовок второго уровня

Заголовки всех шести уровней можно обозначать и с помощью символа («#»)

# H1
## H2
### H3
#### H4
##### H5
###### H6

H1

H2

H3

H4

H5

H6

Параграфы

Для оформления абзацев в html используются теги <p></p>, но в Markdown блок текста автоматически преобразуется в параграф.

Для вставки пустой строки необходимо два раза поставить символ переноса строки (нажать на Enter)

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Consequuntur eius in labore quidem, sequi suscipit! 

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquam aut commodi debitis ipsam nobis perspiciatis sequi, sint unde vitae.

Цитаты

Элемент blockquote представляет содержимое, которое цитируется из другого источника, по желанию с цитатой, которая должна находиться в элементе footer или cite, и по желанию с изменениями в строке, такими как аннотации и сокращения.

Блок-цитата без указания авторства

Tiam, ad mint andaepu dandae nostion secatur sequo quae. Обратите внимание, что вы можете использовать синтаксис Markdown внутри блочной цитаты.

Блок-цитата с указанием авторства

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

>Это пример цитаты,
>в которой перед каждой строкой
>ставится угловая скобка.

>Это пример цитаты,
в которой угловая скобка
ставится только перед началом нового параграфа.
>Второй параграф.

Это пример цитаты, в которой перед каждой строкой ставится угловая скобка.

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

> Первый уровень цитирования
>> Второй уровень цитирования
>>> Третий уровень цитирования
>
>Первый уровень цитирования

Первый уровень цитирования
Второй уровень цитирования
Третий уровень цитирования
Первый уровень цитирования

Таблицы

Таблицы не являются частью основной спецификации Markdown, но Hugo поддерживает их из коробки.

   | Name  | Age |
   | ----- | --- |
   | Bob   | 27  |
   | Alice | 23  |

Name	Age
Bob	27
Alice	23

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

Колонка по левому краю | Колонка по правому краю | Колонка по центру
:--- | ---: | :---:
Текст | Текст | Текст

Колонка по левому краю	Колонка по правому краю	Колонка по центру
Текст	Текст	Текст

Markdown внутри таблицы

| Italics   | Bold     | Code   |
| --------- | -------- | ------ |
| *italics* | **bold** | `code` |

Italics	Bold	Code
italics	bold	`code`

Блоки кода

Блок кода с обратными кавычками

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Блок кода с отступом в четыре пробела

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Блок кода с внутренним шорткодом подсветки Hugo

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Списки

Оформляйте заголовки единообразно. В конце заголовка точку не ставьте.

Правильно	Неправильно
Получение сертификата Создание кластера	Получить сертификат Создание кластера
Получить сертификат Создать кластер

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

Упорядоченный список

First item
Second item
Third item

Чтобы оформить упорядоченный нумерованный список, используйте цифры с символом . или ). Рекомендованный формат разметки: цифра 1 и символ ..

1. Первый пункт
1. Второй пункт
1. Третий пункт

будет отображаться как:

Первый пункт
Второй пункт
Третий пункт

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

Например, разметка:

1. Первый пункт
    1. Вложенный пункт
    1. Вложенный пункт
1. Второй пункт

будет отображаться как:

Первый пункт
1. Вложенный пункт
2. Вложенный пункт
Второй пункт

Неупорядоченный список

List item
Another item
And another item

Вложенный список

Fruit
- Apple
- Orange
- Banana
Dairy
- Milk
- Cheese

Другие элементы - abbr, sub, sup, kbd, mark

GIF is a bitmap image format.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press CTRL+ALT+Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

💡 Структура данных — это контейнер, который хранит данные в определённом формате. Этот контейнер решает, каким образом внешний мир может эти данные считать или изменить.

Приведенная выше цитата взята из книги Роба Пайка talk during Gopherfest, November 18, 2015. ↩︎