📝 Руководство по Markdown

Этот пост демонстрирует все возможности Markdown, поддерживаемые Astro-Theme-Aither. Используйте его как справочник при написании собственных постов. Добавьте эту страницу в закладки — она охватывает весь спектр доступных вам форматирующих средств.

Заголовки

Используйте ## для заголовков разделов, ### для подразделов и #### для под-подразделов. Избегайте # в тексте поста — заголовок поста уже отображается как заголовок верхнего уровня.

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

Заголовки третьего уровня идеально подходят для разделения секции на отдельные темы. Они создают визуальную иерархию, не будучи слишком заметными.

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

Заголовки четвёртого уровня подходят для мелких подразделов. Используйте их экономно — если структура требует глубины больше четырёх уровней, стоит перестроить контент.

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

Обычный текст абзаца течёт естественно. Оставляйте пустую строку между абзацами для их разделения.

Это второй абзац. Старайтесь, чтобы каждый абзац был сосредоточен на одной идее для лучшего восприятия.

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

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

Выделение

Жирный текст с помощью **двойных звёздочек**
Курсивный текст с помощью *одинарных звёздочек*
Жирный курсив с помощью ***тройных звёздочек***
~~Зачёркнутый~~ с помощью ~~двойных тильд~~

Когда использовать каждый стиль

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

Курсив используется для выделения внутри предложения, названий книг и публикаций, технических терминов при первом упоминании и иностранных фраз. Он даёт более мягкое выделение, чем жирный.

~~Зачёркивание~~ полезно для отображения исправлений, устаревшей информации или выполненных пунктов в журнале изменений. У него более узкая область применения, но он ценен, когда необходим.

Ссылки

Встроенная ссылка с синтаксисом [текст](url).

Ссылки также могут указывать на другие посты вашего сайта с помощью относительных путей. Используйте информативный текст ссылки — «прочитайте руководство по markdown» лучше, чем «нажмите сюда». Хороший текст ссылки помогает и читателям, и поисковым системам понять, куда она ведёт.

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

Списки

Маркированный список:

Первый пункт
Второй пункт
- Вложенный пункт
- Ещё один вложенный пункт
Третий пункт

Нумерованный список:

Первый шаг
Второй шаг
1. Подшаг один
2. Подшаг два
Третий шаг

Список задач:

Настроить проект
Написать первый пост
Развернуть в продакшен

Советы по форматированию списков

Списки — один из самых эффективных инструментов веб-текста. Они разбивают плотный текст, делают информацию просматриваемой и чётко передают последовательности или коллекции элементов.

Используйте маркированные списки, когда у элементов нет определённого порядка — функции, требования, варианты или примеры.

Используйте нумерованные списки, когда последовательность важна — шаги процесса, ранжированные элементы или инструкции, которые нужно выполнять по порядку.

Используйте списки задач для отслеживания прогресса, чек-листов проекта или списков дел. Они отображаются как интерактивные чекбоксы во многих средствах просмотра Markdown, хотя в статическом блоге выглядят как визуальные индикаторы.

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

Цитаты

Цель абстракции — не в том, чтобы быть расплывчатым, а в том, чтобы создать новый семантический уровень, на котором можно быть абсолютно точным.

— Эдсгер Дейкстра

Вложенные цитаты:

Первый уровень

Второй уровень

Третий уровень

Использование цитат

Цитаты служат нескольким целям помимо цитирования известных людей:

Указание источников — при ссылке на другую статью, книгу или документ
Выделение важного — акцент на важной информации или предупреждениях
Стиль email-цитирования — показ того, что кто-то сказал в разговоре, на который вы отвечаете
Выносные цитаты — привлечение внимания к ключевому фрагменту вашей собственной статьи

При использовании цитат с атрибуцией размещайте имя автора на отдельной строке с длинным тире, как в примере Дейкстры выше.

Код

Встроенный код с обратными кавычками. Используйте встроенный код для имён функций вроде getPublishedPosts(), путей к файлам вроде src/content/posts/, команд терминала вроде pnpm dev и любых литеральных значений в тексте.

Блок кода с подсветкой синтаксиса:

interface Post {
  title: string;
  date: Date;
  description?: string;
  tags?: string[];
  draft?: boolean;
}

function getPublishedPosts(posts: Post[]): Post[] {
  return posts
    .filter((post) => !post.draft)
    .sort((a, b) => b.date.getTime() - a.date.getTime());
}

@theme {
  --font-sans: 'system-ui', sans-serif;
  --font-serif: 'ui-serif', 'Georgia', serif;
}

Советы по блокам кода

Всегда указывайте идентификатор языка после открывающих тройных обратных кавычек. Это включает подсветку синтаксиса, которая значительно улучшает читаемость. Распространённые идентификаторы: typescript, javascript, css, html, bash, json, python и markdown.

Для команд оболочки используйте bash или sh:

# Установка зависимостей
pnpm install

# Запуск сервера разработки
pnpm dev

# Сборка для продакшена
pnpm build

Для JSON-конфигураций:

{
  "name": "my-blog",
  "version": "1.0.0",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build"
  }
}

Делайте блоки кода сфокусированными. Показывайте только нужные строки, а не весь файл. Если нужен контекст, добавьте комментарий о расположении кода.

Таблицы

Функция	Статус	Примечания
Тёмная тема	Поддерживается	Светлая / Тёмная / Системная
RSS-лента	Встроена	`/rss.xml`
Карта сайта	Автогенерация	Через `@astrojs/sitemap`
SEO	Встроен	Open Graph + canonical

Выравнивание столбцов по правому краю и по центру:

Лево	Центр	Право
Текст	Текст	Текст
Длинный текст	Длинный текст	Длинный текст

Горизонтальная линия

Используйте --- для создания горизонтальной линии:

Контент после линии.

Горизонтальные линии полезны для разделения крупных разделов поста, обозначения смены темы или визуального разбиения очень длинных статей. Используйте их умеренно — если нужны частые разделители, заголовки могут быть лучшим структурным выбором.

Изображения

Изображения поддерживаются стандартным синтаксисом Markdown:

![Альтернативный текст](./image.jpg)

Эта тема ориентирована на типографику, но изображения работают, когда они необходимы.

Подводя итог

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

Пишите ясно, форматируйте единообразно и дайте типографике делать своё дело.