Merge branch 'main' into hd-fix-hero-actions-attrs-class

withastro · Aug 27, 2024 · 31b8ed3 · 31b8ed3
2 parents 8113f56 + 4825271
commit 31b8ed3
Show file tree

Hide file tree

Showing 6 changed files with 96 additions and 65 deletions.
diff --git a/docs/src/content/docs/ru/environmental-impact.md b/docs/src/content/docs/ru/environmental-impact.md
@@ -3,14 +3,11 @@ title: Экологичная документация
 description: Узнайте, как Starlight может помочь создавать экологически сайты с документацией и снижать ваш углеродный след.
 ---
 
-Оценки влияния интернет-индустрии на климат варьируются от [2%][sf] до [4% глобальных выбросов углерода][bbc],
-что близко к выбросам авиационной индустрии.
-Расчет экологического воздействия веб-сайта включает в себя множество сложных факторов,
-но в данном руководстве перечислены несколько советов по снижению экологического следа вашего сайта с документацией.
+Оценки влияния интернет-индустрии на климат варьируются от [2%][sf] до [4% глобальных выбросов углерода][bbc], что близко к выбросам авиационной индустрии.
+Расчет экологического воздействия веб-сайта включает в себя множество сложных факторов, но в данном руководстве перечислены несколько советов по снижению экологического следа вашего сайта с документацией.
 
 Хорошая новость в том, что выбор Starlight — отличное начало.
-Согласно Website Carbon Calculator, этот сайт [чище, чем 99% протестированных веб-страниц][sl-carbon],
-производя 0,01 г CO₂ за каждое посещение страницы.
+Согласно Website Carbon Calculator, этот сайт [чище, чем 99% протестированных веб-страниц][sl-carbon], производя 0,01 г CO₂ за каждое посещение страницы.
 
 ## Вес страницы
 
@@ -34,8 +31,7 @@ Starlight использует [оптимизировацию ресурсов]
 ### Кэширование
 
 Кэширование управляет тем, как долго браузер хранит и повторно использует данные, которые он уже загрузил.
-Хорошая стратегия кэширования гарантирует, что пользователь получает новое содержание как можно быстрее,
-когда оно меняется, но также избегает бесполезной повторной загрузки одного и того же содержания снова и снова, когда оно не изменилось.
+Хорошая стратегия кэширования гарантирует, что пользователь получает новое содержание как можно быстрее, когда оно меняется, но также избегает бесполезной повторной загрузки одного и того же содержания снова и снова, когда оно не изменилось.
 
 Самым распространённым способом настройки кэширования является использование [HTTP-заголовка `Cache-Control`][cache].
 При использовании Starlight вы можете установить длительное время кэширования для всего, что находится в каталоге `/_astro/`.
@@ -45,8 +41,7 @@ Starlight использует [оптимизировацию ресурсов]
 Cache-Control: public, max-age=604800, immutable
 ```
 
-Как настроить кэширование зависит от вашего веб-хоста. Например, Vercel автоматически применяет эту стратегию кэширования без необходимости настройки,
-в то же время вы можете установить [заголовки для Netlify][ntl-headers], добавив файл `public/_headers` в ваш проект:
+Как настроить кэширование зависит от вашего веб-хоста. Например, Vercel автоматически применяет эту стратегию кэширования без необходимости настройки, в то же время вы можете установить [заголовки для Netlify][ntl-headers], добавив файл `public/_headers` в ваш проект:
 
 ```
 /_astro/*
@@ -61,13 +56,10 @@ Cache-Control: public, max-age=604800, immutable
 ## Потребление энергии
 
 То, как реализована веб-страница может влиять на потребление энергии при её запуске на устройстве пользователя.
-За счет минимального использования JavaScript, Starlight снижает объем вычислительных ресурсов, необходимых телефону,
-планшету или компьютеру пользователя для загрузки и отображения страниц.
+За счет минимального использования JavaScript, Starlight снижает объем вычислительных ресурсов, необходимых телефону, планшету или компьютеру пользователя для загрузки и отображения страниц.
 
-Будьте внимательны при добавлении функций, таких как скрипты отслеживания аналитики или контент, зависящий от JavaScript,
-например, встроенные видео, так как они могут увеличить энергопотребление страницы.
-Если вам необходима аналитика, рассмотрите выбор легковесного варианта,
-такого как [Cabin][cabin], [Fathom][fathom] или [Plausible][plausible].
+Будьте внимательны при добавлении функций, таких как скрипты отслеживания аналитики или контент, зависящий от JavaScript, например, встроенные видео, так как они могут увеличить энергопотребление страницы.
+Если вам необходима аналитика, рассмотрите выбор легковесного варианта, такого как [Cabin][cabin], [Fathom][fathom] или [Plausible][plausible].
 Встроенные видео, такие как YouTube и Vimeo, можно улучшить, ожидая [взаимодействие пользователя для загрузки видео][lazy-video].
 Пакеты, такие как [`astro-embed`][embed], могут помочь с часто используемыми сервисами.
 
@@ -88,8 +80,7 @@ Cache-Control: public, max-age=604800, immutable
 Место, где размещена веб-страница, может иметь большое влияние на то, насколько экологичен ваш сайт с документацией.
 Дата-центры и серверные фермы могут оказывать значительное экологическое воздействие, включая высокий энергопотребление и интенсивное использование воды.
 
-Выбор хостинга, использующего возобновляемую энергию, снизит выбросы углерода для вашего сайта.
-[Справочник Green Web][gwb] - один из инструментов, который может помочь вам найти хостинговые компании, работающие с экологически чистой энергией.
+Выбор хостинга, использующего возобновляемую энергию, снизит выбросы углерода для вашего сайта. [Справочник Green Web][gwb] — один из инструментов, который может помочь вам найти хостинговые компании, работающие с экологически чистой энергией.
 
 [gwb]: https://www.thegreenwebfoundation.org/directory/
 
@@ -98,20 +89,21 @@ Cache-Control: public, max-age=604800, immutable
 Хотите сравнивить другие фреймворки для документации?
 Эти тесты с использованием [Website Carbon Calculator][wcc] сравнивают аналогичные страницы, созданные с помощью разных инструментов.
 
-| Фреймворк                   | CO₂ на каждое посещение стр. |
-| --------------------------- | ---------------------------- |
-| [Starlight][sl-carbon]      | 0.01g                        |
-| [VitePress][vp-carbon]      | 0.05g                        |
-| [Docus][dc-carbon]          | 0.05g                        |
-| [Sphinx][sx-carbon]         | 0.07g                        |
-| [MkDocs][mk-carbon]         | 0.10g                        |
-| [Nextra][nx-carbon]         | 0.11g                        |
-| [docsify][dy-carbon]        | 0.11g                        |
-| [Docusaurus][ds-carbon]     | 0.24g                        |
-| [Read the Docs][rtd-carbon] | 0.24g                        |
-| [GitBook][gb-carbon]        | 0.71g                        |
-
-<small>Данные собраны 14 мая 2023 года. Чтобы увидеть актуальные цифры, перейдите по ссылке.</small>
+| Фреймворк                   | CO₂ на каждое посещение стр. | Рейтинг |
+| --------------------------- | ---------------------------- | :-----: |
+| [Starlight][sl-carbon]      | 0.01g                        |   A+    |
+| [Read the Docs][rtd-carbon] | 0.05g                        |   A+    |
+| [Sphinx][sx-carbon]         | 0.06g                        |   A+    |
+| [VitePress][vp-carbon]      | 0.07g                        |   A+    |
+| [Docus][dc-carbon]          | 0.09g                        |   A+    |
+| [docsify][dy-carbon]        | 0.10g                        |    A    |
+| [Nextra][nx-carbon]         | 0.11g                        |    A    |
+| [MkDocs][mk-carbon]         | 0.19g                        |    B    |
+| [Docusaurus][ds-carbon]     | 0.21g                        |    B    |
+| [GitBook][gb-carbon]        | 0.43g                        |    C    |
+| [Mintlify][mt-carbon]       | 1.22g                        |    F    |
+
+<small>Данные собраны 22 июля 2024 года. Нажмите на ссылку для просмотра актуальной информации.</small>
 
 [sl-carbon]: https://www.websitecarbon.com/website/starlight-astro-build-getting-started/
 [vp-carbon]: https://www.websitecarbon.com/website/vitepress-dev-guide-what-is-vitepress/
@@ -123,6 +115,7 @@ Cache-Control: public, max-age=604800, immutable
 [ds-carbon]: https://www.websitecarbon.com/website/docusaurus-io-docs/
 [rtd-carbon]: https://www.websitecarbon.com/website/docs-readthedocs-io-en-stable-index-html/
 [gb-carbon]: https://www.websitecarbon.com/website/docs-gitbook-com/
+[mt-carbon]: https://www.websitecarbon.com/website/mintlify-com-docs-quickstart/
 
 ## Дополнительные ресурсы
 

diff --git a/docs/src/content/docs/ru/manual-setup.mdx b/docs/src/content/docs/ru/manual-setup.mdx
@@ -18,7 +18,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 Starlight является [интеграцией Astro](https://docs.astro.build/ru/guides/integrations-guide/).
 Добавьте её на ваш сайт, запустив команду `astro add` в корневой директории вашего проекта:
 
-<Tabs>
+<Tabs syncKey="pkg">
     <TabItem label="npm">
         ```sh
         npx astro add starlight

diff --git a/docs/src/content/docs/ru/reference/configuration.mdx b/docs/src/content/docs/ru/reference/configuration.mdx
@@ -100,25 +100,33 @@ starlight({
 Настройте элементы навигации боковой панели вашего сайта.
 
 Боковая панель — это массив ссылок и групп ссылок.
-Каждый элемент должен иметь метку `label` и одно из следующих свойств:
+За исключением элементов, использующих `slug`, каждый элемент должен иметь `label` и одно из следующих свойств:
 
-- `link` - одиночная ссылка на определённый URL, например, `'/home'` или `'https://example.com'`.
+- `link` — одиночная ссылка на определённый URL, например, `'/home'` или `'https://example.com'`.
 
-- `items` - массив, содержащий дополнительные ссылки и подгруппы боковой панели.
+- `slug` — ссылка на внутреннюю страницу, например, `'guides/getting-started'`.
 
-- `autogenerate` - объект, указывающий каталог ваших документов для автоматической генерации группы ссылок.
+- `items` — массив, содержащий дополнительные ссылки и подгруппы боковой панели.
+
+- `autogenerate` — объект, указывающий каталог ваших документов для автоматической генерации группы ссылок.
+
+Внутренние ссылки также могут быть указаны в виде строки, а не объекта со свойством `slug`.
 
 ```js
 starlight({
 	sidebar: [
-		// Одиночный элемент ссылки, помеченный как "Главная".
+		// Одиночный элемент ссылки, помеченный как «Главная».
 		{ label: 'Главная', link: '/' },
-		// Группа с надписью "Первые шаги" содержит две ссылки.
+		// Группа с надписью «Первые шаги» содержит четыре ссылки.
 		{
 			label: 'Первые шаги',
 			items: [
-				{ label: 'Введение', link: '/intro' },
-				{ label: 'Следующие шаги', link: '/next-steps' },
+				// Использование `slug` для внутренних ссылок.
+				{ slug: 'intro' },
+				{ slug: 'installation' },
+				// Или использование сокращения для обозначения внутренних ссылок.
+				'tutorial',
+				'next-steps',
 			],
 		},
 		// Группа, связывающая все страницы директории reference.
@@ -141,16 +149,13 @@ starlight({
 
 Автогенерируемые подгруппы по умолчанию уважают свойство `collapsed` своей родительской группы. Установите свойство `autogenerate.collapsed`, чтобы переопределить его.
 
-```js {5,16}
+```js {5,13}
 sidebar: [
   // Группа свёрнутых ссылок.
   {
     label: 'Свёрнутые ссылки',
     collapsed: true,
-    items: [
-      { label: 'Введение', link: '/intro' },
-      { label: 'Следующие шаги', link: '/next-steps' },
-    ],
+		items: ['intro', 'next-steps'],
   },
   // Развёрнутая группа, содержащая свёрнутые автогенерируемые подгруппы.
   {
@@ -192,21 +197,37 @@ sidebar: [
 #### `SidebarItem`
 
 ```ts
-type SidebarItem = {
-	label: string;
-	translations?: Record<string, string>;
-	badge?: string | BadgeConfig;
-} & (
-	| {
-			link: string;
-			attrs?: Record<string, string | number | boolean | undefined>;
-	  }
-	| { items: SidebarItem[]; collapsed?: boolean }
-	| {
-			autogenerate: { directory: string; collapsed?: boolean };
-			collapsed?: boolean;
-	  }
-);
+type SidebarItem =
+	| string
+	| ({
+			translations?: Record<string, string>;
+			badge?: string | BadgeConfig;
+	  } & (
+			| {
+					// Обычная ссылка
+					link: string;
+					label: string;
+					attrs?: Record<string, string | number | boolean | undefined>;
+			  }
+			| {
+					// Внутренняя ссылка
+					slug: string;
+					label?: string;
+					attrs?: Record<string, string | number | boolean | undefined>;
+			  }
+			| {
+					// Группа ссылок
+					label: string;
+					items: SidebarItem[];
+					collapsed?: boolean;
+			  }
+			| {
+					// Автоматически созданная группа ссылок
+					label: string;
+					autogenerate: { directory: string; collapsed?: boolean };
+					collapsed?: boolean;
+			  }
+	  ));
 ```
 
 #### `BadgeConfig`

diff --git a/docs/src/content/docs/ru/reference/frontmatter.md b/docs/src/content/docs/ru/reference/frontmatter.md
@@ -115,10 +115,10 @@ hero:
     - text: Расскажите мне больше
       link: /getting-started/
       icon: right-arrow
-      variant: primary
     - text: Просмотр на GitHub
       link: https://github.com/astronaut/my-project
       icon: external
+      variant: minimal
       attrs:
         rel: me
 ---
@@ -166,8 +166,8 @@ interface HeroConfig {
   actions?: Array<{
     text: string;
     link: string;
-    variant: 'primary' | 'secondary' | 'minimal';
-    icon: string;
+    variant?: 'primary' | 'secondary' | 'minimal';
+    icon?: string;
     attrs?: Record<string, string | number | boolean>;
   }>;
 }

diff --git a/docs/src/content/docs/ru/resources/community-content.mdx b/docs/src/content/docs/ru/resources/community-content.mdx
@@ -84,6 +84,11 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components';
 		title="Добавление структурированных данных на страницы Starlight"
 		description="Узнайте, как создавать динамические структурированные данные JSON-LD для страниц документации"
 	/>
+	<LinkCard
+		href="https://starlight-examples.netlify.app/"
+		title="Примеры Starlight"
+		description="Коллекция вставок StackBlitz, демонстрирующих практические способы работы с сайтами документации Starlight"
+	/>
 </CardGrid>
 
 ## Видеоконтент

diff --git a/docs/src/content/docs/ru/resources/plugins.mdx b/docs/src/content/docs/ru/resources/plugins.mdx
@@ -25,7 +25,7 @@ sidebar:
 	/>
 </CardGrid>
 
-### Плагины сообщества
+### Плагины от сообщества
 
 <CardGrid>
 	<LinkCard
@@ -78,6 +78,18 @@ sidebar:
 		title="starlight-versions"
 		description="Отображение версий для страниц документации Starlight."
 	/>
+	<LinkCard
+		href="https://inox-tools.fryuni.dev/star-warp"
+		title="star-warp"
+		description="Пользователи смогут осуществлять поиск на вашем веб-сайте напрямую из панели поиска своего браузера."
+	/>
+</CardGrid>
+
+### Темы от сообщества
+
+Тема — это плагин Starlight, который изменяет внешний вид сайта с помощью переопределения компонентов, пользовательского CSS или других новых возможностей.
+
+<CardGrid>
 	<LinkCard
 		href="https://github.com/HiDeoo/starlight-theme-rapide"
 		title="starlight-theme-rapide"