Пропустить до содержимого
Starlight

Создание контента в Markdown

Starlight поддерживает весь синтаксис Markdown в файлах с расширением .md, а также синтаксис YAML для определения метаданных, таких как заголовок и описание.

Пожалуйста, обратитесь к документации MDX или документации Markdoc, если вы используете эти форматы файлов, так как синтаксисы могут различаться от Markdown.

Форматирование текста

Текст может быть жирным, курсивом или зачеркнутым.

Текст может быть **жирным**, _курсивом_ или ~~зачеркнутым~~.

Вы можете ссылаться на другую страницу.

Вы можете [ссылаться на другую страницу](/ru/getting-started/).

Вы можете выделить код обратными кавычками.

Вы можете выделить `код` обратными кавычками.

Изображения

Изображения в Starlight используют встроенную оптимизацию ресурсов в Astro.

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

Иллюстрация планет и звезд с надписью "astro"

![Иллюстрация планет и звезд с надписью "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)

Также поддерживаются относительные пути к изображениям, хранящиеся локально в вашем проекте.

// src/content/docs/page-1.md

![Ракета в космосе](../../assets/images/rocket.svg)

Заголовки

Вы можете структурировать контент, используя заголовки. Заголовки в Markdown обозначаются количеством символов # в начале строки.

Как структурировать контент страницы

Starlight настроен так, чтобы автоматически использовать заголовок вашей страницы в качестве заголовка верхнего уровня и включать заголовок “Обзор” в начале оглавления каждой страницы. Мы рекомендуем начинать каждую страницу с обычного текстового содержания абзаца и использовать заголовки на странице от <h2> и ниже:

---
title: Руководство по Markdown
description: Как использовать Markdown в Starlight
---

Эта страница описывает, как использовать Markdown в Starlight.

## Форматирование текста

## Заголовки

Автоматические якорные ссылки для заголовков

Использование заголовков в Markdown автоматически создает якорные ссылки, позволяя вам ссылаться на определенные разделы вашей страницы:

---
title: Моя страница с контентом
description: Как использовать встроенные в Starlight якорные ссылки.
---

## Введение

Я могу создать ссылку на [заключение](#conclusion) ниже на этой же странице.

## Заключение

`https://my-site.com/page1/#introduction` навигирует непосредственно к разделу "Введение" на моей странице.

Заголовки уровня 2 (<h2>) и уровня 3 (<h3>) автоматически появятся в оглавлении страницы.

Вставки

Вставки, либо “предостережения” или “вызовы”, полезны для отображения дополнительной информации рядом с основным контентом страницы.

Starlight предоставляет специальный синтаксис Markdown для отображения вставок. Вставки должны быть обернуты парой тройных двоеточий ::: и могут иметь тип note, tip, caution или danger.

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

Вставка “Заметка”

:::note
Starlight - это инструмент для создания сайтов с документацией,
построенный с использованием [Astro](https://astro.build/). Вы можете начать создавать запустив команду:

```sh
npm create astro@latest -- --template starlight
```

:::

Настраиваемые заголовки вставок

Вы можете указать свой заголовок вставки в квадратных скобках после типа вставки, например, :::tip[Знали ли вы?].

:::tip[Знали ли вы?]
Astro позволяет создавать быстрые сайты с помощью ["архитектуры островов"](https://docs.astro.build/ru/concepts/islands/)
:::

Больше типов вставок

Вставки “Caution” и “danger” полезны для привлечения внимания пользователя к деталям, которые могут сбивать с толку. Если вы часто используете их, это может быть признаком того, что может быть нужно пересмотреть то, что вы документируете.

:::caution
Если вы не уверены, что хотите отличный сайт с документацией, подумайте дважды, прежде чем использовать [Starlight](../../).
:::

:::danger
Your users may be more productive and find your product easier to use thanks to helpful Starlight features.

- Четкая навигация
- Цветовая тема, настраиваемая пользователем
- [Поддержка i18n](/ru/guides/i18n)

:::

Цитаты

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

Цитаты обозначаются символом > в начале каждой строки.

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

Блоки кода

Блок кода обозначается блоком с тремя обратными апострофами ``` в начале и в конце. Вы можете указать язык программирования после открывающих апострофов.

// Javascript код с подсветкой синтаксиса.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};
```js
// Javascript код с подсветкой синтаксиса.
var fun = function lang(l) {
  dateformat.i18n = require('./lang/' + l);
  return true;
};
```
Длинные блоки кода в одну строку не должны переноситься. Они должны прокручиваться горизонтально, если они слишком длинные. Эта строка должна быть достаточно длинной, чтобы продемонстрировать это.

Другие возможности Markdown

Starlight поддерживает все синтаксические возможности Markdown, такие как списки и таблицы. Посмотрите шпаргалку по Markdown от The Markdown Guide для изучения всех возможностей синтаксиса Markdown.