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

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

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

Метаданные

Вы можете настроить отдельные страницы в Starlight, установив значения в их заглавной части. Метаданные устанавливаются в верхней части ваших файлов между разделителями ---:

---
title: Заголовок страницы
---

Содержимое страницы следует за вторым `---`.

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

Встроенные стили

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

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

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

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

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

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

Изображения

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

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

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

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

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

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

Заголовки

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

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

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

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

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

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

## Заголовки

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

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

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

## Введение

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

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

`https://my-site.com/page1/#введение` переходит непосредственно к моему Введению.

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

Узнайте больше о том, как Astro обрабатывает идентификаторы заголовков, в документации Astro

Вставки

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

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

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

Вставка «Заметка»

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

npm create astro@latest -- --template starlight

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

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

:::

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

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

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

Пользовательские иконки вставок

Вы можете указать пользовательскую иконку для вставки в фигурных скобках после типа панели или пользовательского заголовка, например, :::tip{icon="heart"} или :::tip[Знаете ли вы?]{icon="heart"} соответственно. В качестве имени должна использоваться одна из встроенных иконок Starlight.

:::tip{icon="heart"}
Astro помогает создавать более быстрые веб-сайты с помощью [архитектуры островков](https://docs.astro.build/ru/concepts/islands/).
:::

Другие типы вставок

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

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

:::danger
Ваши пользователи могут быть более продуктивными и находить ваш продукт более простым в использовании благодаря полезным функциям Starlight.

- Чёткая навигация
- Цветовая тема, настраиваемая пользователем
- [Поддержка 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;
};
```

Возможности Expressive Code

Starlight использует Expressive Code для расширения возможностей форматирования блоков кода. Текстовые маркеры и плагины оконных рамок Expressive Code включены по умолчанию. Рендеринг блоков кода можно настроить с помощью параметра конфигурации expressiveCode Starlight.

Текстовые маркеры

Вы можете выделить определённые строки или части блоков кода с помощью текстовых маркеров Expressive Code в первой строке вашего блока кода. Используйте фигурные скобки ({ }), чтобы выделить целые строки, и кавычки, чтобы выделить строки текста.

Существует три стиля выделения: нейтральный для привлечения внимания к коду, зелёный для обозначения вставленного кода и красный для обозначения удалённого кода. И текст, и целые строки можно пометить с помощью маркера по умолчанию или в сочетании с ins= и del= для получения желаемого выделения.

Expressive Code предоставляет несколько вариантов настройки внешнего вида примеров кода. Многие из них можно комбинировать для получения наглядных примеров кода. Ознакомьтесь с документацией Expressive Code, чтобы узнать о расширенных возможностях. доступный. Некоторые из наиболее распространённых примеров показаны ниже:

Пометка целых строк и диапазонов строк с помощью маркера { }:
```
function demo() {
  // Эта строка (#2) и следующая выделены
  return 'Это строка №3 этого фрагмента';
}
```
- Markdown/MDX
- Markdoc
```js {2-3} function demo() { // Эта строка (#2) и следующая выделены return 'Это строка №3 этого фрагмента'; } ```
```js {% meta="{2-3}" %} function demo() { // Эта строка (#2) и следующая выделены return 'Это строка №3 этого фрагмента'; } ```

Пометка выделенного текста с помощью маркера " " или регулярных выражений:

// Отдельные термины также могут быть выделены
function demo() {
  return 'Поддерживаются даже регулярные выражения';
}

Markdown/MDX
Markdoc

```js "Отдельные термины" /даже.*выражения/
// Отдельные термины также могут быть выделены
function demo() {
  return 'Поддерживаются даже регулярные выражения';
}
```

```js {% meta="'Отдельные термины' /даже.*выражения/" %}
// Отдельные термины также могут быть выделены
function demo() {
  return 'Поддерживаются даже регулярные выражения';
}
```

Пометка текста или строк как вставленных или удалённых с помощью ins или del:

function demo() {
  console.log('Это вставленные и удалённые типы маркеров');
  // Оператор return использует тип маркера по умолчанию
  return true;
}

Markdown/MDX
Markdoc

```js "return true;" ins="вставленные" del="удалённые"
function demo() {
  console.log('Это вставленные и удалённые типы маркеров');
  // Оператор return использует тип маркера по умолчанию
  return true;
}
```

```js {% meta="'return true;' ins='вставленные' del='удалённые'" %}
function demo() {
  console.log('Это вставленные и удалённые типы маркеров');
  // Оператор return использует тип маркера по умолчанию
  return true;
}
```

Объединение подсветки синтаксиса с синтаксисом типа diff:

function thisIsJavaScript() {
  // Весь этот блок выделяется как JavaScript,
  // и мы можем добавить к нему маркеры различий!
  console.log('Старый код, который нужно удалить')
  console.log('Новый и блестящий код!')
}

Markdown/MDX
Markdoc

```diff lang="js"
  function thisIsJavaScript() {
    // Весь этот блок выделяется как JavaScript,
    // и мы можем добавить к нему маркеры различий!
-   console.log('Устаревший код, который нужно удалить')
+   console.log('Обновлённый и крутой код!')
  }
```

```diff {% meta="lang='js'" %}
  function thisIsJavaScript() {
    // Весь этот блок выделяется как JavaScript,
    // и мы можем добавить к нему маркеры различий!
-   console.log('Устаревший код, который нужно удалить')
+   console.log('Обновлённый и крутой код!')
  }
```

Рамки и заголовки

Блоки кода могут отображаться внутри оконного фрейма. Рамка, похожая на окно терминала, будет использоваться для языков сценариев оболочки (например, bash или sh). Другие языки отображаются внутри рамки в стиле редактора кода, если они включают заголовок.

Необязательный заголовок блока кода может быть установлен либо с помощью атрибута title="..." после открывающих обратных кавычек блока кода и идентификатора языка, либо с помощью комментария к имени файла в первых строках кода.

Добавление вкладки имени файла с помощью комментария

console.log('Привет, мир!');

Markdown/MDX
Markdoc

```js
// my-test-file.js
console.log('Привет, мир!');
```

```js
// my-test-file.js
console.log('Привет, мир!');
```

Добавление заголовка в окне терминала

npm install

Markdown/MDX
Markdoc

```bash title="Установка зависимостей…"
npm install
```

```bash {% title="Установка зависимостей…" %}
npm install
```

Отключение оконных рамок с помощью frame="none"

echo "Это не отображается как терминал, несмотря на использование языка bash"

Markdown/MDX
Markdoc

```bash frame="none"
echo "Это не отображается как терминал, несмотря на использование языка bash"
```

```bash {% frame="none" %}
echo "Это не отображается как терминал, несмотря на использование языка bash"
```

Спойлеры

Спойлеры (также известные как «раскрытия» или «аккордеоны») полезны для того, чтобы скрыть содержимое, которое не имеет непосредственного отношения к делу. Пользователи могут нажать на краткое содержание, чтобы развернуть его и просмотреть полный текст.

Используйте стандартные элементы HTML <details> и <summary> в вашем Markdown-контенте, чтобы создать виджет раскрытия информации.

Внутри элемента <details> можно использовать любой другой синтаксис Markdown.

Где и когда созвездие Андромеды видно лучше всего?

Созвездие Андромеды наиболее заметно на ночном небе в ноябре на широтах от +90° до -40°.

<details>
<summary>Где и когда созвездие Андромеды видно лучше всего?</summary>

[Созвездие Андромеды](<https://ru.wikipedia.org/wiki/%D0%90%D0%BD%D0%B4%D1%80%D0%BE%D0%BC%D0%B5%D0%B4%D0%B0_(%D1%81%D0%BE%D0%B7%D0%B2%D0%B5%D0%B7%D0%B4%D0%B8%D0%B5)>) наиболее заметно на ночном небе в ноябре на широтах от `+90°` до `-40°`.

</details>

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

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

Расширенная конфигурация Markdown и MDX

Starlight использует Markdown и рендерер MDX от Astro, основанный на remark и rehype. Вы можете добавить поддержку пользовательского синтаксиса и поведения, добавив remarkPlugins или rehypePlugins в свой файл конфигурации Astro. Дополнительную информацию см. в статье Плагины Markdown в документации Astro.

Markdoc

Starlight поддерживает создание контента в Markdoc с помощью экспериментальной интеграции с Astro и пресета Starlight Markdoc.

Создание нового проекта с Markdoc

Начните новый проект Starlight с предварительно настроенным Markdoc с помощью команды create astro:

npm create astro@latest -- --template starlight/markdoc

pnpm create astro --template starlight/markdoc

yarn create astro --template starlight/markdoc

Добавление Markdoc в существующий проект

Если у вас уже есть сайт Starlight и вы хотите добавить Markdoc, выполните следующие действия.

Добавьте интеграцию Markdoc:
- npm
- pnpm
- Yarn
Окно терминала
npx astro add markdoc
Окно терминала
pnpm astro add markdoc
Окно терминала
yarn astro add markdoc
Установите пресет Markdoc для Starlight:
- npm
- pnpm
- Yarn
Окно терминала
npm install @astrojs/starlight-markdoc
Окно терминала
pnpm add @astrojs/starlight-markdoc
Окно терминала
yarn add @astrojs/starlight-markdoc

Создайте файл конфигурации Markdoc по адресу markdoc.config.mjs и используйте пресет Markdoc:

import { defineMarkdocConfig } from '@astrojs/markdoc/config';
import starlightMarkdoc from '@astrojs/starlight-markdoc';

export default defineMarkdocConfig({
  extends: [starlightMarkdoc()],
});

Чтобы узнать больше о синтаксисе и возможностях Markdoc, смотрите документацию или Руководство по интеграции Markdoc в Astro.

Настройка пресета Markdoc

Пресет starlightMarkdoc() принимает следующие параметры конфигурации:

`headingLinks`

тип: boolean
по умолчанию: true

Определяет, будут ли заголовки отображаться с кликабельной ссылкой-якорем. Эквивалентно опции markdown.headingLinks, которая применяется к файлам Markdown и MDX.

export default defineMarkdocConfig({
  // Отключение поддержки ссылок-якорей для заголовков по умолчанию
  extends: [starlightMarkdoc({ headingLinks: false })],
});