diff --git a/docs/src/content/docs/ru/components/icons.mdx b/docs/src/content/docs/ru/components/icons.mdx index ca95a2400bb..770dabc20b4 100644 --- a/docs/src/content/docs/ru/components/icons.mdx +++ b/docs/src/content/docs/ru/components/icons.mdx @@ -95,7 +95,7 @@ import { Icon } from '@astrojs/starlight/components'; ### `name` **обязательный** -**тип:** `string` +**тип:** [`StarlightIcon`](/ru/reference/icons/#тип-starlighticon) Имя отображаемой иконки, из набора [встроенных иконок Starlight](/ru/reference/icons/#все-иконки). diff --git a/docs/src/content/docs/ru/components/using-components.mdx b/docs/src/content/docs/ru/components/using-components.mdx index 1b5510cae58..dcdd658e3d2 100644 --- a/docs/src/content/docs/ru/components/using-components.mdx +++ b/docs/src/content/docs/ru/components/using-components.mdx @@ -81,14 +81,14 @@ Starlight применяет стандартную стилистику к со Используйте тип [`ComponentProps`](https://docs.astro.build/ru/guides/typescript/#%D1%82%D0%B8%D0%BF-componentprops) из `astro/types` для ссылки на `Props`, принимаемые компонентом, даже если они не экспортируются самим компонентом. Это может быть полезно при обёртке или расширении существующего компонента. -В следующем примере используется `ComponentProps` для получения типа параметров, принимаемых встроенным компонентом Starlight `Icon`: +В следующем примере используется `ComponentProps` для получения типа параметров, принимаемых встроенным компонентом Starlight `Badge`: ```astro --- // src/components/Example.astro import type { ComponentProps } from 'astro/types'; -import { Icon } from '@astrojs/starlight/icon'; +import { Badge } from '@astrojs/starlight/components'; -type IconProps = ComponentProps; +type BadgeProps = ComponentProps; --- ``` diff --git a/docs/src/content/docs/ru/guides/authoring-content.mdx b/docs/src/content/docs/ru/guides/authoring-content.mdx index 5fab7f58a50..a150d8f5fa4 100644 --- a/docs/src/content/docs/ru/guides/authoring-content.mdx +++ b/docs/src/content/docs/ru/guides/authoring-content.mdx @@ -220,13 +220,13 @@ var fun = function lang(l) { ### Возможности Expressive Code -Starlight использует [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) для расширения возможностей форматирования блоков кода. +Starlight использует [Expressive Code](https://expressive-code.com/) для расширения возможностей форматирования блоков кода. Текстовые маркеры и плагины оконных рамок Expressive Code включены по умолчанию. Рендеринг блоков кода можно настроить с помощью [параметра конфигурации `expressiveCode`](/ru/reference/configuration/#expressivecode) Starlight. #### Текстовые маркеры -Вы можете выделить определённые строки или части блоков кода с помощью [текстовых маркеров Expressive Code](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#usage-in-markdown--mdx-documents) в первой строке вашего блока кода. +Вы можете выделить определённые строки или части блоков кода с помощью [текстовых маркеров Expressive Code](https://expressive-code.com/key-features/text-markers/) в первой строке вашего блока кода. Используйте фигурные скобки (`{ }`), чтобы выделить целые строки, и кавычки, чтобы выделить строки текста. Существует три стиля выделения: нейтральный для привлечения внимания к коду, зелёный для обозначения вставленного кода и красный для обозначения удалённого кода. @@ -234,10 +234,10 @@ Starlight использует [Expressive Code](https://github.com/expressive-c Expressive Code предоставляет несколько вариантов настройки внешнего вида примеров кода. Многие из них можно комбинировать для получения наглядных примеров кода. -Ознакомьтесь с [документацией Expressive Code](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md), чтобы узнать о расширенных возможностях. доступный. +Ознакомьтесь с [документацией Expressive Code](https://expressive-code.com/key-features/text-markers/#configuration), чтобы узнать о расширенных возможностях. доступный. Некоторые из наиболее распространённых примеров показаны ниже: -- [Пометка целых строк и диапазонов строк с помощью маркера `{ }`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-entire-lines--line-ranges): +- [Пометка целых строк и диапазонов строк с помощью маркера `{ }`](https://expressive-code.com/key-features/text-markers/#marking-full-lines--line-ranges): ```js {2-3} function demo() { @@ -255,7 +255,7 @@ Expressive Code предоставляет несколько вариантов ``` ```` -- [Пометка выделенного текста с помощью маркера `" "` или регулярных выражений](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#marking-individual-text-inside-lines): +- [Пометка выделенного текста с помощью маркера `" "` или регулярных выражений](https://expressive-code.com/key-features/text-markers/#marking-individual-text-inside-lines): ```js "Отдельные термины" /даже.*выражения/ // Отдельные термины также могут быть выделены @@ -273,7 +273,7 @@ Expressive Code предоставляет несколько вариантов ``` ```` -- [Пометка текста или строк как вставленных или удалённых с помощью `ins` или `del`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#selecting-marker-types-mark-ins-del): +- [Пометка текста или строк как вставленных или удалённых с помощью `ins` или `del`](https://expressive-code.com/key-features/text-markers/#selecting-inline-marker-types-mark-ins-del): ```js "return true;" ins="вставленные" del="удалённые" function demo() { @@ -293,7 +293,7 @@ Expressive Code предоставляет несколько вариантов ``` ```` -- [Объединение подсветки синтаксиса с синтаксисом типа `diff`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-text-markers/README.md#combining-syntax-highlighting-with-diff-like-syntax): +- [Объединение подсветки синтаксиса с синтаксисом типа `diff`](https://expressive-code.com/key-features/text-markers/#combining-syntax-highlighting-with-diff-like-syntax): ```diff lang="js" function thisIsJavaScript() { @@ -323,7 +323,7 @@ Expressive Code предоставляет несколько вариантов Необязательный заголовок блока кода может быть установлен либо с помощью атрибута `title="..."` после открывающих обратных кавычек блока кода и идентификатора языка, либо с помощью комментария к имени файла в первых строках кода. -- [Добавление вкладки имени файла с помощью комментария](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) +- [Добавление вкладки имени файла с помощью комментария](https://expressive-code.com/key-features/frames/#code-editor-frames) ```js // my-test-file.js @@ -337,7 +337,7 @@ Expressive Code предоставляет несколько вариантов ``` ```` -- [Добавление заголовка в окне терминала](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#adding-titles-open-file-tab-or-terminal-window-title) +- [Добавление заголовка в окне терминала](https://expressive-code.com/key-features/frames/#terminal-frames) ```bash title="Установка зависимостей…" npm install @@ -349,7 +349,7 @@ Expressive Code предоставляет несколько вариантов ``` ```` -- [Отключение оконных рамок с помощью `frame="none"`](https://github.com/expressive-code/expressive-code/blob/main/packages/%40expressive-code/plugin-frames/README.md#overriding-frame-types) +- [Отключение оконных рамок с помощью `frame="none"`](https://expressive-code.com/key-features/frames/#overriding-frame-types) ```bash frame="none" echo "Это не отображается как терминал, несмотря на использование языка bash" diff --git a/docs/src/content/docs/ru/guides/i18n.mdx b/docs/src/content/docs/ru/guides/i18n.mdx index 779b886a7e1..194ade3dd40 100644 --- a/docs/src/content/docs/ru/guides/i18n.mdx +++ b/docs/src/content/docs/ru/guides/i18n.mdx @@ -222,7 +222,7 @@ import UIStringsList from '~/components/ui-strings-list.astro'; - Блоки кода Starlight основаны на библиотеке [Expressive Code](https://github.com/expressive-code/expressive-code). + Блоки кода Starlight основаны на библиотеке [Expressive Code](https://expressive-code.com/). Вы можете установить переводы для строк пользовательского интерфейса в том же файле JSON, используя ключи `expressiveCode`: ```json diff --git a/docs/src/content/docs/ru/guides/site-search.mdx b/docs/src/content/docs/ru/guides/site-search.mdx index 661d5618b8e..4f153372194 100644 --- a/docs/src/content/docs/ru/guides/site-search.mdx +++ b/docs/src/content/docs/ru/guides/site-search.mdx @@ -1,6 +1,8 @@ --- title: Поиск по сайту description: Узнайте о встроенных в Starlight функциях поиска по сайту и о том, как их настроить. +tableOfContents: + maxHeadingLevel: 4 --- import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; @@ -110,13 +112,62 @@ title: Частично проиндексированная страница #### Конфигурация DocSearch -Плагин Starlight DocSearch также поддерживает настройку компонента DocSearch с помощью следующих дополнительных опций: +Плагин Starlight DocSearch поддерживает настройку компонента DocSearch с помощью следующих встроенных опций: - `maxResultsPerGroup`: Ограничивает количество результатов, отображаемых для каждой группы поиска. По умолчанию `5`. - `disableUserPersonalization`: Предотвращает сохранение недавних поисков и избранных элементов пользователя в локальном хранилище. По умолчанию `false`. - `insights`: Включает плагин Algolia Insights и отправляет события поиска в ваш индекс DocSearch. По умолчанию `false`. - `searchParameters`: Объект, настраивающий [параметры поиска Algolia](https://www.algolia.com/doc/api-reference/search-api-parameters/). +##### Дополнительные опции DocSearch + +Необходим отдельный файл конфигурации для передачи параметров функции, таких как `transformItems()` или `resultsFooterComponent()`, в компонент DocSearch. + + + +1. Создайте файл TypeScript, экспортирующий вашу конфигурацию DocSearch. + + ```ts + // src/config/docsearch.ts + import type { DocSearchClientOptions } from '@astrojs/starlight-docsearch'; + + export default { + appId: 'YOUR_APP_ID', + apiKey: 'YOUR_SEARCH_API_KEY', + indexName: 'YOUR_INDEX_NAME', + getMissingResultsUrl({ query }) { + return `https://github.com/algolia/docsearch/issues/new?title=${query}`; + }, + // ... + } satisfies DocSearchClientOptions; + ``` + +2. Передайте путь к вашему файлу конфигурации плагину Starlight DocSearch в `astro.config.mjs`. + + ```js {11-13} + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + import starlightDocSearch from '@astrojs/starlight-docsearch'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'Сайт с DocSearch', + plugins: [ + starlightDocSearch({ + clientOptionsModule: './src/config/docsearch.ts', + }), + ], + }), + ], + }); + ``` + + + +Смотрите [Документацию по API клиента DocSearch JavaScript](https://docsearch.algolia.com/docs/api/), чтобы узнать все поддерживаемые параметры. + #### Перевод пользовательского интерфейса DocSearch По умолчанию DocSearch предоставляет только английские строки пользовательского интерфейса. diff --git a/docs/src/content/docs/ru/reference/configuration.mdx b/docs/src/content/docs/ru/reference/configuration.mdx index d8a76e2af29..928147b14ea 100644 --- a/docs/src/content/docs/ru/reference/configuration.mdx +++ b/docs/src/content/docs/ru/reference/configuration.mdx @@ -268,6 +268,11 @@ export default defineConfig({ label: '简体中文', lang: 'zh-CN', }, + // Арабская документация в `src/content/docs/ar/` + ar: { + label: 'العربية', + dir: 'rtl', + }, // Русская документация в `src/content/docs/ru/` ru: { label: 'Русский', @@ -383,10 +388,10 @@ starlight({ **тип:** `StarlightExpressiveCodeOptions | boolean` **по умолчанию:** `true` -Starlight использует [Expressive Code](https://github.com/expressive-code/expressive-code/tree/main/packages/astro-expressive-code) для визуализации блоков кода и добавляет поддержку выделения частей примеров кода, добавления имён файлов к блокам кода и многое другое. +Starlight использует [Expressive Code](https://expressive-code.com) для визуализации блоков кода и добавляет поддержку выделения частей примеров кода, добавления имён файлов к блокам кода и многое другое. Смотрите руководство [Блоки кода](/ru/guides/authoring-content/#блоки-кода), чтобы узнать, как использовать синтаксис выразительного кода в Markdown и MDX-содержимом. -Вы также можете использовать любые стандартные [параметры конфигурации Expressive Code](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#configuration), как некоторые свойства, специфичные для Starlight, установив их в опции `expressiveCode` Starlight. +Вы также можете использовать любые стандартные [параметры конфигурации Expressive Code](https://expressive-code.com/reference/configuration/), как некоторые свойства, специфичные для Starlight, установив их в опции `expressiveCode` Starlight. Например, установите опцию `styleOverrides` в Expressive Code, чтобы переопределить CSS по умолчанию. Это позволяет настраивать код, например, сделать блокам кода закругленные углы: ```js ins={2-4} @@ -413,7 +418,7 @@ starlight({ **по умолчанию:** `['starlight-dark', 'starlight-light']` Установите темы, используемые для оформления блоков кода. -См. [документацию по темам Expressive Code](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/README.md#themes) для получения подробной информации о поддерживаемых форматах тем. +См. [документацию по темам Expressive Code](https://expressive-code.com/guides/themes/) для получения подробной информации о поддерживаемых форматах тем. По умолчанию Starlight использует тёмный и светлый варианты [темы Night Owl](https://github.com/sdras/night-owl-vscode-theme) Сары Драснер. @@ -446,16 +451,32 @@ starlight({ ### `pagefind` -**тип:** `boolean` +**тип:** boolean | PagefindOptions **по умолчанию:** `true` -Определите, включен ли в Starlight поставщик поиска по сайту по умолчанию — [Pagefind](https://pagefind.app/). +Настройте стандартный поставщик поиска по сайту Starlight — [Pagefind](https://pagefind.app/). Установите значение `false`, чтобы отключить индексацию вашего сайта с помощью Pagefind. Это также скроет стандартный пользовательский интерфейс поиска, если он используется. Pagefind не может быть включен, если для параметра [`prerender`](#prerender) установлено значение `false`. +Установите `pagefind` в объект, чтобы настроить клиент поиска Pagefind. +Смотрите главу [Настройка ранжирования результатов Pagefind](https://pagefind.app/docs/ranking/) в документации Pagefind для получения дополнительной информации о том, как использовать параметр `pagefind.ranking` для управления расчётом ранжирования результатов поиска. + +#### `PagefindOptions` + +```ts +interface PagefindOptions { + ranking?: { + pageLength?: number; + termFrequency?: number; + termSaturation?: number; + termSimilarity?: number; + }; +} +``` + ### `prerender` **тип:** `boolean` diff --git a/docs/src/content/docs/ru/reference/frontmatter.md b/docs/src/content/docs/ru/reference/frontmatter.md index eb46880d2bc..31f6aea592e 100644 --- a/docs/src/content/docs/ru/reference/frontmatter.md +++ b/docs/src/content/docs/ru/reference/frontmatter.md @@ -273,7 +273,7 @@ pagefind: false **тип:** `boolean` **по умолчанию:** `false` -Установите, следует ли считать эту страницу черновиком и не включать её в [продакшен-сборки](https://docs.astro.build/ru/reference/cli-reference/#astro-build) и [группы автогенерируемых ссылок](/ru/guides/sidebar/#автогенерируемые-группы). Установите значение `true`, чтобы пометить страницу как черновик и сделать её видимой только во время разработки. +Установите, следует ли считать эту страницу черновиком и не включать её в [продакшен-сборки](https://docs.astro.build/ru/reference/cli-reference/#astro-build). Установите значение `true`, чтобы пометить страницу как черновик и сделать её видимой только во время разработки. ```md --- @@ -283,6 +283,9 @@ draft: true --- ``` +Поскольку черновики страниц не включаются в выходные данные сборки, вы не можете добавить черновики страниц напрямую в конфигурацию боковой панели вашего сайта, используя [слаги](/ru/guides/sidebar/#внутренние-ссылки). +Черновики страниц в каталогах, используемых для [автоматически сгенерированных групп боковой панели](/ru/guides/sidebar/#автогенерируемые-группы), автоматически исключаются в продакшен-сборках. + ### `sidebar` **тип:** [`SidebarConfig`](#sidebarconfig) diff --git a/docs/src/content/docs/ru/reference/icons.mdx b/docs/src/content/docs/ru/reference/icons.mdx index 0c0a88828ec..78554bb3297 100644 --- a/docs/src/content/docs/ru/reference/icons.mdx +++ b/docs/src/content/docs/ru/reference/icons.mdx @@ -10,6 +10,19 @@ Starlight предоставляет набор общих иконок, кот Иконки можно отображать с помощью компонента [``](/ru/components/icons/). Они также часто используются в других компонентах, таких как [карточки](/ru/components/cards/) или в настройках, таких как [hero](/ru/reference/frontmatter/#hero). +## Тип `StarlightIcon` + +Используйте тип TypeScript `StarlightIcon`, чтобы ссылаться на названия [встроенных иконок Starlight](#все-иконки). + +```ts {2} /icon: (StarlightIcon)/ +// src/icon.ts +import type { StarlightIcon } from '@astrojs/starlight/types'; + +function getIconLabel(icon: StarlightIcon) { + // … +} +``` + ## Все иконки Список всех доступных иконок показан ниже с их соответствующими именами. Кликните по значку, чтобы скопировать код компонента для него. diff --git a/docs/src/content/docs/ru/reference/plugins.md b/docs/src/content/docs/ru/reference/plugins.md index 860d67a0638..ecfd48d124d 100644 --- a/docs/src/content/docs/ru/reference/plugins.md +++ b/docs/src/content/docs/ru/reference/plugins.md @@ -89,7 +89,7 @@ export default { **тип:** `(integration: AstroIntegration) => void` -Функция обратного вызова для добавления [Astro integration](https://docs.astro.build/ru/reference/integrations-reference/), необходимой плагину. +Функция обратного вызова для добавления [интеграции Astro](https://docs.astro.build/ru/reference/integrations-reference/), необходимой плагину. В следующем примере плагин сначала проверяет, настроена ли [интеграция Astro с React](https://docs.astro.build/ru/guides/integrations-guide/react/), и, если нет, использует `addIntegration()` для её добавления: