From b505922d8681211af6259f69a8a47c8af479037d Mon Sep 17 00:00:00 2001 From: Atharva Pise Date: Tue, 28 Nov 2023 16:59:57 +0530 Subject: [PATCH 01/68] i18n(hi): update `showcase.mdx` (#1153) --- docs/src/content/docs/hi/showcase.mdx | 53 +++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/src/content/docs/hi/showcase.mdx diff --git a/docs/src/content/docs/hi/showcase.mdx b/docs/src/content/docs/hi/showcase.mdx new file mode 100644 index 00000000000..428862f0387 --- /dev/null +++ b/docs/src/content/docs/hi/showcase.mdx @@ -0,0 +1,53 @@ +--- +title: Starlight प्रदर्शन +description: Starlight और सामुदायिक टूल से निर्मित साइटों की खोज करें जो Starlight का विस्तार करते हैं! +--- + +:::tip[अपनी स्वयं की साइट जोड़ें!] +क्या आपने Starlight साइट या Starlight के लिए कोई उपकरण बनाया है? +इस पेज पर एक लिंक जोड़कर एक PR खोलें! +::: + +## साइटें + +import ShowcaseSites from '../../../components/showcase-sites.astro'; + +Starlight का उपयोग पहले से ही उत्पादन में किया जा रहा है। ये वेब पर मौजूद कुछ साइटें हैं: + + + +[GitHub पर Starlight का उपयोग करने वाली सभी सार्वजनिक परियोजना रिपो](https://github.com/withastro/starlight/network/dependents) देखें। + +## सामुदायिक प्लगइन्स + +import { CardGrid, LinkCard } from '@astrojs/starlight/components'; + +ये सामुदायिक उपकरण, प्लगइन्स और एकीकरण Starlight की कार्यक्षमता को बढ़ाने के लिए उसके साथ काम करते हैं। + + + + + + + + From 631c5aeccba60254ff649712f93ba30495775edf Mon Sep 17 00:00:00 2001 From: Michael Gwynne Date: Tue, 28 Nov 2023 11:36:47 +0000 Subject: [PATCH 02/68] Upgrade `@astrojs/sitemap` to latest (#1156) Co-authored-by: Chris Swithinbank --- .changeset/quiet-trains-know.md | 5 +++++ packages/starlight/package.json | 2 +- pnpm-lock.yaml | 14 +++++++++----- 3 files changed, 15 insertions(+), 6 deletions(-) create mode 100644 .changeset/quiet-trains-know.md diff --git a/.changeset/quiet-trains-know.md b/.changeset/quiet-trains-know.md new file mode 100644 index 00000000000..00c22fa0cb3 --- /dev/null +++ b/.changeset/quiet-trains-know.md @@ -0,0 +1,5 @@ +--- +'@astrojs/starlight': patch +--- + +Updates `@astrojs/sitemap` dependency to the latest version diff --git a/packages/starlight/package.json b/packages/starlight/package.json index e488bee712a..da3a22a4c21 100644 --- a/packages/starlight/package.json +++ b/packages/starlight/package.json @@ -174,7 +174,7 @@ }, "dependencies": { "@astrojs/mdx": "^1.1.0", - "@astrojs/sitemap": "^3.0.0", + "@astrojs/sitemap": "^3.0.3", "@pagefind/default-ui": "^1.0.3", "@types/mdast": "^3.0.11", "astro-expressive-code": "^0.29.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ff742fa2c28..885f44bafef 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -139,8 +139,8 @@ importers: specifier: ^1.1.0 version: 1.1.0(astro@3.2.3) '@astrojs/sitemap': - specifier: ^3.0.0 - version: 3.0.0 + specifier: ^3.0.3 + version: 3.0.3 '@pagefind/default-ui': specifier: ^1.0.3 version: 1.0.3 @@ -325,11 +325,11 @@ packages: dependencies: prismjs: 1.29.0 - /@astrojs/sitemap@3.0.0: - resolution: {integrity: sha512-qm7npHuUW4q3OOmulqhJ1g69jEQu0Sdc6P8NbOzqIoosj/L+3v4i8dtKBnp6n1UQ4Sx8H8Vdi3Z/On7i9/ZJhw==} + /@astrojs/sitemap@3.0.3: + resolution: {integrity: sha512-+GRKp1yho9dpHBcMcU6JpbL41k0yYZghOkNsMRb8QIRflbGHvd787tdv9oIZ5NJj0SqAuOlqp2UpqLkJXuAe2A==} dependencies: sitemap: 7.1.1 - zod: 3.21.1 + zod: 3.22.4 dev: false /@astrojs/tailwind@5.0.0(astro@3.2.3)(tailwindcss@3.3.3): @@ -6890,5 +6890,9 @@ packages: /zod@3.21.1: resolution: {integrity: sha512-+dTu2m6gmCbO9Ahm4ZBDapx2O6ZY9QSPXst2WXjcznPMwf2YNpn3RevLx4KkZp1OPW/ouFcoBtBzFz/LeY69oA==} + /zod@3.22.4: + resolution: {integrity: sha512-iC+8Io04lddc+mVqQ9AZ7OQ2MrUKGN+oIQyq1vemgt46jwCwLfhq7/pwnBnNXXXZb8VTVLKwp9EDkx+ryxIWmg==} + dev: false + /zwitch@2.0.4: resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==} From eb12a4542081f95e1d89c14479020110c45bdb79 Mon Sep 17 00:00:00 2001 From: "Houston (Bot)" <108291165+astrobot-houston@users.noreply.github.com> Date: Tue, 28 Nov 2023 03:40:55 -0800 Subject: [PATCH 03/68] [ci] release (#1110) Co-authored-by: github-actions[bot] --- .changeset/calm-bananas-nail.md | 5 ----- .changeset/quiet-trains-know.md | 5 ----- .changeset/tidy-mails-brake.md | 5 ----- examples/basics/package.json | 2 +- examples/tailwind/package.json | 2 +- packages/starlight/CHANGELOG.md | 40 ++++++++++++++++++++------------- packages/starlight/package.json | 2 +- pnpm-lock.yaml | 4 ++-- 8 files changed, 30 insertions(+), 35 deletions(-) delete mode 100644 .changeset/calm-bananas-nail.md delete mode 100644 .changeset/quiet-trains-know.md delete mode 100644 .changeset/tidy-mails-brake.md diff --git a/.changeset/calm-bananas-nail.md b/.changeset/calm-bananas-nail.md deleted file mode 100644 index 9432c9d024d..00000000000 --- a/.changeset/calm-bananas-nail.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@astrojs/starlight": patch ---- - -Fix minor punctuation typo in Hindi UI string diff --git a/.changeset/quiet-trains-know.md b/.changeset/quiet-trains-know.md deleted file mode 100644 index 00c22fa0cb3..00000000000 --- a/.changeset/quiet-trains-know.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@astrojs/starlight': patch ---- - -Updates `@astrojs/sitemap` dependency to the latest version diff --git a/.changeset/tidy-mails-brake.md b/.changeset/tidy-mails-brake.md deleted file mode 100644 index e616d36215b..00000000000 --- a/.changeset/tidy-mails-brake.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'@astrojs/starlight': patch ---- - -Internal: fix import issue with expressive-code diff --git a/examples/basics/package.json b/examples/basics/package.json index 4ee1af4d600..2e747ff75cb 100644 --- a/examples/basics/package.json +++ b/examples/basics/package.json @@ -11,7 +11,7 @@ "astro": "astro" }, "dependencies": { - "@astrojs/starlight": "^0.13.0", + "@astrojs/starlight": "^0.13.1", "astro": "^3.2.3", "sharp": "^0.32.5" } diff --git a/examples/tailwind/package.json b/examples/tailwind/package.json index 86f40cd8eb3..d23740c4ad9 100644 --- a/examples/tailwind/package.json +++ b/examples/tailwind/package.json @@ -11,7 +11,7 @@ "astro": "astro" }, "dependencies": { - "@astrojs/starlight": "^0.13.0", + "@astrojs/starlight": "^0.13.1", "@astrojs/starlight-tailwind": "^2.0.1", "@astrojs/tailwind": "^5.0.0", "astro": "^3.2.3", diff --git a/packages/starlight/CHANGELOG.md b/packages/starlight/CHANGELOG.md index ec731526f7b..1a9dd55137e 100644 --- a/packages/starlight/CHANGELOG.md +++ b/packages/starlight/CHANGELOG.md @@ -1,5 +1,15 @@ # @astrojs/starlight +## 0.13.1 + +### Patch Changes + +- [#1111](https://github.com/withastro/starlight/pull/1111) [`cb19d07`](https://github.com/withastro/starlight/commit/cb19d07d6192ffb732ac6fcf9df04d4f098bfc1f) Thanks [@at-the-vr](https://github.com/at-the-vr)! - Fix minor punctuation typo in Hindi UI string + +- [#1156](https://github.com/withastro/starlight/pull/1156) [`631c5ae`](https://github.com/withastro/starlight/commit/631c5aeccba60254ff649712f93ba30495775edf) Thanks [@votemike](https://github.com/votemike)! - Updates `@astrojs/sitemap` dependency to the latest version + +- [#1109](https://github.com/withastro/starlight/pull/1109) [`0c25c1f`](https://github.com/withastro/starlight/commit/0c25c1f33bbfe311724784530c30ada44eb5de19) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Internal: fix import issue with expressive-code + ## 0.13.0 ### Minor Changes @@ -17,12 +27,12 @@ import starlight from '@astrojs/starlight'; export default defineConfig({ - trailingSlash: 'always', - integrations: [ - starlight({ - // ... - }), - ], + trailingSlash: 'always', + integrations: [ + starlight({ + // ... + }), + ], }); ``` @@ -370,16 +380,16 @@ ```css :root { - --sl-hue-accent: 234; - --sl-color-accent-low: hsl(var(--sl-hue-accent), 54%, 20%); - --sl-color-accent: hsl(var(--sl-hue-accent), 100%, 60%); - --sl-color-accent-high: hsl(var(--sl-hue-accent), 100%, 87%); + --sl-hue-accent: 234; + --sl-color-accent-low: hsl(var(--sl-hue-accent), 54%, 20%); + --sl-color-accent: hsl(var(--sl-hue-accent), 100%, 60%); + --sl-color-accent-high: hsl(var(--sl-hue-accent), 100%, 87%); } :root[data-theme='light'] { - --sl-color-accent-high: hsl(var(--sl-hue-accent), 80%, 30%); - --sl-color-accent: hsl(var(--sl-hue-accent), 90%, 60%); - --sl-color-accent-low: hsl(var(--sl-hue-accent), 88%, 90%); + --sl-color-accent-high: hsl(var(--sl-hue-accent), 80%, 30%); + --sl-color-accent: hsl(var(--sl-hue-accent), 90%, 60%); + --sl-color-accent-low: hsl(var(--sl-hue-accent), 88%, 90%); } ``` @@ -758,8 +768,8 @@ ```json { - "search.label": "Suchen", - "search.shortcutLabel": "(Drücke / zum Suchen)" + "search.label": "Suchen", + "search.shortcutLabel": "(Drücke / zum Suchen)" } ``` diff --git a/packages/starlight/package.json b/packages/starlight/package.json index da3a22a4c21..9e6b94da004 100644 --- a/packages/starlight/package.json +++ b/packages/starlight/package.json @@ -1,6 +1,6 @@ { "name": "@astrojs/starlight", - "version": "0.13.0", + "version": "0.13.1", "description": "Build beautiful, high-performance documentation websites with Astro", "scripts": { "test": "vitest", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 885f44bafef..db414b3142f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -103,7 +103,7 @@ importers: examples/basics: dependencies: '@astrojs/starlight': - specifier: ^0.13.0 + specifier: ^0.13.1 version: link:../../packages/starlight astro: specifier: ^3.2.3 @@ -115,7 +115,7 @@ importers: examples/tailwind: dependencies: '@astrojs/starlight': - specifier: ^0.13.0 + specifier: ^0.13.1 version: link:../../packages/starlight '@astrojs/starlight-tailwind': specifier: ^2.0.1 From f82cb340532747aaadff451271df2d6a018d8231 Mon Sep 17 00:00:00 2001 From: delucis Date: Tue, 28 Nov 2023 11:41:37 +0000 Subject: [PATCH 04/68] [ci] format --- packages/starlight/CHANGELOG.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/packages/starlight/CHANGELOG.md b/packages/starlight/CHANGELOG.md index 1a9dd55137e..58482e719d8 100644 --- a/packages/starlight/CHANGELOG.md +++ b/packages/starlight/CHANGELOG.md @@ -27,12 +27,12 @@ import starlight from '@astrojs/starlight'; export default defineConfig({ - trailingSlash: 'always', - integrations: [ - starlight({ - // ... - }), - ], + trailingSlash: 'always', + integrations: [ + starlight({ + // ... + }), + ], }); ``` @@ -380,16 +380,16 @@ ```css :root { - --sl-hue-accent: 234; - --sl-color-accent-low: hsl(var(--sl-hue-accent), 54%, 20%); - --sl-color-accent: hsl(var(--sl-hue-accent), 100%, 60%); - --sl-color-accent-high: hsl(var(--sl-hue-accent), 100%, 87%); + --sl-hue-accent: 234; + --sl-color-accent-low: hsl(var(--sl-hue-accent), 54%, 20%); + --sl-color-accent: hsl(var(--sl-hue-accent), 100%, 60%); + --sl-color-accent-high: hsl(var(--sl-hue-accent), 100%, 87%); } :root[data-theme='light'] { - --sl-color-accent-high: hsl(var(--sl-hue-accent), 80%, 30%); - --sl-color-accent: hsl(var(--sl-hue-accent), 90%, 60%); - --sl-color-accent-low: hsl(var(--sl-hue-accent), 88%, 90%); + --sl-color-accent-high: hsl(var(--sl-hue-accent), 80%, 30%); + --sl-color-accent: hsl(var(--sl-hue-accent), 90%, 60%); + --sl-color-accent-low: hsl(var(--sl-hue-accent), 88%, 90%); } ``` @@ -768,8 +768,8 @@ ```json { - "search.label": "Suchen", - "search.shortcutLabel": "(Drücke / zum Suchen)" + "search.label": "Suchen", + "search.shortcutLabel": "(Drücke / zum Suchen)" } ``` From 304faa4a0386a03a6560c8e206894f23edc6044c Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Wed, 29 Nov 2023 11:21:42 +0100 Subject: [PATCH 05/68] Add Deploy to Vercel buttons to starter project READMEs (#1164) --- examples/basics/README.md | 1 + examples/tailwind/README.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/examples/basics/README.md b/examples/basics/README.md index f95661b59b0..b51abaabcd4 100644 --- a/examples/basics/README.md +++ b/examples/basics/README.md @@ -8,6 +8,7 @@ npm create astro@latest -- --template starlight [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics) [![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics) +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs) > 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! diff --git a/examples/tailwind/README.md b/examples/tailwind/README.md index a4a8ce623b3..bbe7db31c15 100644 --- a/examples/tailwind/README.md +++ b/examples/tailwind/README.md @@ -8,6 +8,8 @@ npm create astro@latest -- --template starlight/tailwind [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/tailwind) [![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/tailwind) +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Ftailwind&project-name=my-starlight-docs&repository-name=my-starlight-docs) + > 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! From 98ce3630b90a40374cb6792226be202fa784a561 Mon Sep 17 00:00:00 2001 From: delucis Date: Wed, 29 Nov 2023 10:22:21 +0000 Subject: [PATCH 06/68] [ci] format --- examples/tailwind/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/tailwind/README.md b/examples/tailwind/README.md index bbe7db31c15..43ad3998217 100644 --- a/examples/tailwind/README.md +++ b/examples/tailwind/README.md @@ -10,7 +10,6 @@ npm create astro@latest -- --template starlight/tailwind [![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/tailwind) [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Ftailwind&project-name=my-starlight-docs&repository-name=my-starlight-docs) - > 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! ## 🚀 Project Structure From 64d25c125c80375ff7b2cbf749f3c35d49b8bc98 Mon Sep 17 00:00:00 2001 From: Leo Voon Date: Wed, 29 Nov 2023 22:46:22 +0800 Subject: [PATCH 07/68] i18n(zh-CN): Update getting-started.mdx (#1165) --- .../content/docs/zh-cn/getting-started.mdx | 99 ++++++++++++++----- 1 file changed, 73 insertions(+), 26 deletions(-) diff --git a/docs/src/content/docs/zh-cn/getting-started.mdx b/docs/src/content/docs/zh-cn/getting-started.mdx index d2d06db0cb9..25f5736bc8d 100644 --- a/docs/src/content/docs/zh-cn/getting-started.mdx +++ b/docs/src/content/docs/zh-cn/getting-started.mdx @@ -5,17 +5,20 @@ description: 了解如何使用 Astro 的 Starlight 开始构建下一个文档 import { Tabs, TabItem } from '@astrojs/starlight/components'; -## 创建一个新项目 - Starlight 是一个基于 [Astro](https://astro.build) 框架构建的全功能文档主题。 +查看 [手动配置](/zh-cn/manual-setup/) 以将Starlight添加到现有的Astro项目中。 +这个指南将帮助你开始一个新项目。 + +## 快速入门 -你可以使用以下命令创建一个新的 Astro + Starlight 项目： +### 创建一个新项目 + +在你的终端中运行以下命令来创建一个新的Astro + Starlight项目： ```sh -# 使用 npm 创建一个新项目 npm create astro@latest -- --template starlight ``` @@ -23,7 +26,6 @@ npm create astro@latest -- --template starlight ```sh -# 使用 pnpm 创建一个新项目 pnpm create astro --template starlight ``` @@ -31,7 +33,6 @@ pnpm create astro --template starlight ```sh -# 使用 yarn 创建一个新项目 yarn create astro --template starlight ``` @@ -45,24 +46,69 @@ yarn create astro --template starlight [在 StackBlitz 上打开模板](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)。 ::: -## 使用 Starlight 创建内容 +### 启动开发服务器 -Starlight 已经准备好让你添加新的内容，或者将你现有的文件带过来！ +在本地工作时，[Astro的开发服务器](https://docs.astro.build/zh-cn/reference/cli-reference/#astro-dev)允许你预览你的工作，并在你进行更改时自动刷新你的浏览器。 -### 文件格式 +在你的项目目录中，运行以下命令来启动开发服务器： -Starlight 支持使用 Markdown 和 MDX 来编写内容。（你可以通过安装实验性的 [Astro Markdoc 集成](https://docs.astro.build/zh-cn/guides/integrations-guide/markdoc/) 来添加对 Markdoc 的支持。） + + -### 添加页面 +```sh +npm run dev +``` -在 `src/content/docs/` 中创建 `.md` 或 `.mdx` 文件，就可以自动将新页面添加到你的站点中。添加子文件夹来组织你的文件，并创建多个路径段： + + +```sh +pnpm dev ``` -src/content/docs/hello-world.md => your-site.com/hello-world -src/content/docs/guides/faq.md => your-site.com/guides/faq + + + + +```sh +yarn dev ``` -### 类型安全的 frontmatter + + + +这将在你的终端上记录一个包含本地预览网址的消息。 +打开这个网址开始浏览你的网站。 + +### 添加内容 + +Starlight已经准备好让你添加新内容或导入你现有的文件！ + +#### 文件格式 + +Starlight支持在Markdown和MDX中编写内容，无需进行任何配置。 +你可以通过安装实验性的[Astro Markdoc](https://docs.astro.build/zh-cn/guides/integrations-guide/markdoc/)集成来添加对Markdoc的支持。 + +#### 添加页面 + +通过在 `src/content/docs/` 中创建 `.md` 或 `.mdx` 文件来为你的站点添加新页面。 +使用子文件夹来组织你的文件并创建多个路径段。 + +例如，以下文件结构将在 `example.com/hello-world` 和 `example.com/guides/faq` 生成页面： + +import FileTree from '../../../components/file-tree.astro'; + + + +- src/ + - content/ + - docs/ + - guides/ + - faq.md + - hello-world.md + + + +#### 类型安全的 frontmatter 所有 Starlight 页面都共享一个可自定义的 [frontmatter 属性集](/zh-cn/reference/frontmatter/)，用于控制页面的外观： @@ -75,16 +121,19 @@ description: This is a page in my Starlight-powered site 如果你忘记了任何重要的东西，Starlight 会提醒你。 -## 部署你的 Starlight 网站 +### 下一步 -一旦你创建并自定义了你的 Starlight 网站，你就可以将它部署到你选择的 web 服务器或托管平台上，包括 Netlify、Vercel、GitHub Pages 等等。 - -[在 Astro 文档中了解如何部署 Astro 网站。](https://docs.astro.build/zh-cn/guides/deploy/) +- **配置：** 在[自定义 Starlight](/zh-cn/guides/customization/)中了解常见选项。 +- **导航：** 使用[侧边栏导航](/zh-cn/guides/sidebar/)指南设置你的侧边栏。 +- **组件：** 在[组件](/zh-cn/guides/components/)指南中发现内置的卡片、标签页等更多内容。 +- **部署：** 使用Astro文档中的[部署你的 Astro 站点](https://docs.astro.build/zh-cn/guides/deploy/)指南发布你的站点。 ## 更新 Starlight :::tip[提示] -由于 Starlight 是 beta 软件，所以会经常更新和改进。请务必定期更新 Starlight！ +由于 Starlight 是 beta 软件，所以会经常更新和改进。 + +请务必定期更新 Starlight！ ::: Starlight 是一个 Astro 集成，可以像任何 `@astrojs/*` 集成一样更新： @@ -93,7 +142,6 @@ Starlight 是一个 Astro 集成，可以像任何 `@astrojs/*` 集成一样更 ```sh -# 使用 npm 升级 Starlight npm install @astrojs/starlight@latest ``` @@ -101,7 +149,6 @@ npm install @astrojs/starlight@latest ```sh -# 使用 pnpm 升级 Starlight pnpm upgrade @astrojs/starlight --latest ``` @@ -109,21 +156,21 @@ pnpm upgrade @astrojs/starlight --latest ```sh -# 使用 yarn 升级 Starlight yarn upgrade @astrojs/starlight --latest ``` -你可以在 [Starlight 更新日志](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md) 中查看每个版本的变动列表。 +查阅 [Starlight 更新日志](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md)中每个版本的变更列表。 ## Starlight 故障排除 本站点的参考部分提供了 Starlight [项目配置](/zh-cn/reference/configuration/)和[单个页面 frontmatter 配置](/zh-cn/reference/frontmatter/)信息。使用这些页面来确保你的 Starlight 网站已正确配置和运行。 -请参阅侧边栏中不断增长的指南列表，以获取有关添加内容和自定义 Starlight 网站的帮助。 +请参阅侧边栏中的指南列表，以获取有关添加内容和自定义 Starlight 网站的帮助。 -如果你在这些文档中找不到答案，请访问[完整的 Astro 文档](https://docs.astro.build) 以获取完整的 Astro 文档。你的问题可能是通过了解 Starlight 主题下 Astro 的工作原理来解决的。 +如果你在这些文档中找不到答案，请访问[完整的 Astro 文档](https://docs.astro.build/zh-cn/) 以获取完整的 Astro 文档。 +你的问题可能是通过了解 Starlight 主题下 Astro 的工作原理来解决的。 你也可以检查任何已知的 [GitHub 上的 Starlight issues](https://github.com/withastro/starlight/issues)，并在 [Astro Discord](https://astro.build/chat/) 上从我们活跃的、友好的社区中获得帮助！在我们的 `#support` 论坛中发布带有 “starlight” 标签的问题，或者访问我们专门的 `#starlight` 频道来讨论当前的开发和更多内容！ From e5a863a98b2e5335e122ca440dcb84e9426939b4 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Wed, 29 Nov 2023 20:25:09 +0100 Subject: [PATCH 08/68] Expose localized UI strings in route data (#1135) --- .changeset/pink-mirrors-cough.md | 7 ++++ docs/src/content/docs/reference/overrides.md | 6 ++++ packages/starlight/404.astro | 2 +- .../__tests__/basics/route-data.test.ts | 10 ++++++ .../__tests__/i18n/route-data.test.ts | 32 +++++++++++++++++++ .../__tests__/i18n/translations.test.ts | 8 ----- packages/starlight/components/EditLink.astro | 6 ++-- .../components/FallbackContentNotice.astro | 5 ++- .../starlight/components/LanguageSelect.astro | 5 ++- .../starlight/components/LastUpdated.astro | 6 ++-- .../components/MobileMenuToggle.astro | 6 ++-- .../components/MobileTableOfContents.astro | 6 ++-- packages/starlight/components/PageFrame.astro | 9 ++---- .../starlight/components/Pagination.astro | 8 ++--- packages/starlight/components/Search.astro | 26 +++++++++------ packages/starlight/components/SkipLink.astro | 5 ++- .../components/TableOfContents.astro | 6 ++-- .../starlight/components/ThemeSelect.astro | 11 +++---- .../utils/createTranslationSystem.ts | 11 +++++-- packages/starlight/utils/route-data.ts | 3 ++ 20 files changed, 110 insertions(+), 68 deletions(-) create mode 100644 .changeset/pink-mirrors-cough.md create mode 100644 packages/starlight/__tests__/i18n/route-data.test.ts diff --git a/.changeset/pink-mirrors-cough.md b/.changeset/pink-mirrors-cough.md new file mode 100644 index 00000000000..c43df8ed5da --- /dev/null +++ b/.changeset/pink-mirrors-cough.md @@ -0,0 +1,7 @@ +--- +'@astrojs/starlight': minor +--- + +Exposes localized UI strings in route data + +Component overrides can now access a `labels` object in their props which includes all the localized UI strings for the current page. \ No newline at end of file diff --git a/docs/src/content/docs/reference/overrides.md b/docs/src/content/docs/reference/overrides.md index 387e485d11c..9bd6cc9cdad 100644 --- a/docs/src/content/docs/reference/overrides.md +++ b/docs/src/content/docs/reference/overrides.md @@ -135,6 +135,12 @@ JavaScript `Date` object representing when this page was last updated if enabled `URL` object for the address where this page can be edited if enabled. +#### `labels` + +**Type:** `Record` + +An object containing UI strings localized for the current page. See the [“Translate Starlight’s UI”](/guides/i18n/#translate-starlights-ui) guide for a list of all the available keys. + --- ## Components diff --git a/packages/starlight/404.astro b/packages/starlight/404.astro index 913c5143f64..61358234e8d 100644 --- a/packages/starlight/404.astro +++ b/packages/starlight/404.astro @@ -26,7 +26,7 @@ const fallbackEntry: StarlightDocsEntry = { head: [], hero: { tagline: t('404.text'), actions: [] }, pagefind: false, - sidebar: { hidden: false }, + sidebar: { hidden: false, attrs: {} }, }, render: async () => ({ Content: EmptyContent, diff --git a/packages/starlight/__tests__/basics/route-data.test.ts b/packages/starlight/__tests__/basics/route-data.test.ts index 13522d02243..eacd5334de9 100644 --- a/packages/starlight/__tests__/basics/route-data.test.ts +++ b/packages/starlight/__tests__/basics/route-data.test.ts @@ -85,3 +85,13 @@ test('uses explicit last updated date from frontmatter', () => { expect(data.lastUpdated).toBeInstanceOf(Date); expect(data.lastUpdated).toEqual(route.entry.data.lastUpdated); }); + +test('includes localized labels', () => { + const route = routes[0]!; + const data = generateRouteData({ + props: { ...route, headings: [{ depth: 1, slug: 'heading-1', text: 'Heading 1' }] }, + url: new URL('https://example.com'), + }); + expect(data.labels).toBeDefined(); + expect(data.labels['skipLink.label']).toBe('Skip to content'); +}); diff --git a/packages/starlight/__tests__/i18n/route-data.test.ts b/packages/starlight/__tests__/i18n/route-data.test.ts new file mode 100644 index 00000000000..57beed0c1d8 --- /dev/null +++ b/packages/starlight/__tests__/i18n/route-data.test.ts @@ -0,0 +1,32 @@ +import { expect, test, vi } from 'vitest'; +import { generateRouteData } from '../../utils/route-data'; +import { routes } from '../../utils/routing'; + +vi.mock('astro:content', async () => + (await import('../test-utils')).mockedAstroContent({ + docs: [ + ['fr/index.mdx', { title: 'Accueil' }], + ['pt-br/index.mdx', { title: 'Pagina inicial' }], + ], + }) +); + +test('includes localized labels (fr)', () => { + const route = routes[0]!; + const data = generateRouteData({ + props: { ...route, headings: [{ depth: 1, slug: 'heading-1', text: 'Heading 1' }] }, + url: new URL('https://example.com'), + }); + expect(data.labels).toBeDefined(); + expect(data.labels['skipLink.label']).toBe('Aller au contenu'); +}); + +test('includes localized labels (pt-br)', () => { + const route = routes[1]!; + const data = generateRouteData({ + props: { ...route, headings: [{ depth: 1, slug: 'heading-1', text: 'Heading 1' }] }, + url: new URL('https://example.com'), + }); + expect(data.labels).toBeDefined(); + expect(data.labels['skipLink.label']).toBe('Pular para o conteúdo'); +}); diff --git a/packages/starlight/__tests__/i18n/translations.test.ts b/packages/starlight/__tests__/i18n/translations.test.ts index a8442166f83..1e9fd032337 100644 --- a/packages/starlight/__tests__/i18n/translations.test.ts +++ b/packages/starlight/__tests__/i18n/translations.test.ts @@ -22,14 +22,6 @@ describe('useTranslations()', () => { expect(t('page.editLink')).toBe(translations.en?.['page.editLink']); }); - test('returns a pick method for filtering by key', () => { - const t = useTranslations('en'); - expect(t.pick('tableOfContents.')).toEqual({ - 'tableOfContents.onThisPage': 'On this page', - 'tableOfContents.overview': 'Overview', - }); - }); - test('uses built-in translations for regional variants', () => { const t = useTranslations('pt-br'); expect(t('page.nextLink')).toBe(translations.pt?.['page.nextLink']); diff --git a/packages/starlight/components/EditLink.astro b/packages/starlight/components/EditLink.astro index f5f5f65b1cf..74be4c8f79d 100644 --- a/packages/starlight/components/EditLink.astro +++ b/packages/starlight/components/EditLink.astro @@ -1,17 +1,15 @@ --- import Icon from '../user-components/Icon.astro'; import type { Props } from '../props'; -import { useTranslations } from '../utils/translations'; -const t = useTranslations(Astro.props.locale); -const { editUrl } = Astro.props; +const { editUrl, labels } = Astro.props; --- { editUrl && ( - {t('page.editLink')} + {labels['page.editLink']} ) } diff --git a/packages/starlight/components/FallbackContentNotice.astro b/packages/starlight/components/FallbackContentNotice.astro index 171eeb157aa..44d553a433a 100644 --- a/packages/starlight/components/FallbackContentNotice.astro +++ b/packages/starlight/components/FallbackContentNotice.astro @@ -1,14 +1,13 @@ --- import Icon from '../user-components/Icon.astro'; import type { Props } from '../props'; -import { useTranslations } from '../utils/translations'; -const t = useTranslations(Astro.props.locale); +const { labels } = Astro.props; ---

{t('i18n.untranslatedContent')}{labels['i18n.untranslatedContent']}

diff --git a/packages/starlight/components/LanguageSelect.astro b/packages/starlight/components/LanguageSelect.astro index 077935b3e53..c85292dc7bb 100644 --- a/packages/starlight/components/LanguageSelect.astro +++ b/packages/starlight/components/LanguageSelect.astro @@ -1,7 +1,6 @@ --- import config from 'virtual:starlight/user-config'; import { localizedUrl } from '../utils/localizedUrl'; -import { useTranslations } from '../utils/translations'; import Select from './Select.astro'; import type { Props } from '../props'; @@ -12,7 +11,7 @@ function localizedPathname(locale: string | undefined): string { return localizedUrl(Astro.url, locale).pathname; } -const t = useTranslations(Astro.props.locale); +const { labels } = Astro.props; --- { @@ -20,7 +19,7 @@ const t = useTranslations(Astro.props.locale); diff --git a/packages/starlight/utils/createTranslationSystem.ts b/packages/starlight/utils/createTranslationSystem.ts index 188b176c4fc..9f2a5bf386b 100644 --- a/packages/starlight/utils/createTranslationSystem.ts +++ b/packages/starlight/utils/createTranslationSystem.ts @@ -19,10 +19,16 @@ export function createTranslationSystem( /** * Generate a utility function that returns UI strings for the given `locale`. + * + * Also includes an `all()` method for getting the entire dictionary. + * * @param {string | undefined} [locale] * @example * const t = useTranslations('en'); - * const label = t('search.label'); // => 'Search' + * const label = t('search.label'); + * // => 'Search' + * const dictionary = t.all(); + * // => { 'skipLink.label': 'Skip to content', 'search.label': 'Search', ... } */ return function useTranslations(locale: string | undefined) { const lang = localeToLang(locale, config.locales, config.defaultLocale); @@ -32,8 +38,7 @@ export function createTranslationSystem( userTranslations[lang] ); const t = (key: K) => dictionary[key]; - t.pick = (startOfKey: string) => - Object.fromEntries(Object.entries(dictionary).filter(([k]) => k.startsWith(startOfKey))); + t.all = () => dictionary; return t; }; } diff --git a/packages/starlight/utils/route-data.ts b/packages/starlight/utils/route-data.ts index 966f780e84e..484fea08d52 100644 --- a/packages/starlight/utils/route-data.ts +++ b/packages/starlight/utils/route-data.ts @@ -29,6 +29,8 @@ export interface StarlightRouteData extends Route { lastUpdated: Date | undefined; /** URL object for the address where this page can be edited if enabled. */ editUrl: URL | undefined; + /** Record of UI strings localized for the current page. */ + labels: ReturnType['all']>; } export function generateRouteData({ @@ -48,6 +50,7 @@ export function generateRouteData({ toc: getToC(props), lastUpdated: getLastUpdated(props), editUrl: getEditUrl(props), + labels: useTranslations(locale).all(), }; } From 7c0b8cb334c501678f7ab87cce372cddfdde34ed Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Wed, 29 Nov 2023 20:31:39 +0100 Subject: [PATCH 09/68] Add a `pagefind` boolean flag to user config (#1144) Co-authored-by: Sarah Rainsberger --- .changeset/beige-shoes-whisper.md | 5 +++++ docs/src/content/docs/reference/configuration.mdx | 10 ++++++++++ docs/src/content/docs/reference/overrides.md | 4 ++++ packages/starlight/components/Header.astro | 9 ++++++++- packages/starlight/index.ts | 1 + packages/starlight/utils/user-config.ts | 7 +++++++ 6 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 .changeset/beige-shoes-whisper.md diff --git a/.changeset/beige-shoes-whisper.md b/.changeset/beige-shoes-whisper.md new file mode 100644 index 00000000000..e544c5d3423 --- /dev/null +++ b/.changeset/beige-shoes-whisper.md @@ -0,0 +1,5 @@ +--- +'@astrojs/starlight': minor +--- + +Adds a configuration option to disable site indexing with Pagefind and the default search UI diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx index 4808adb1365..9e546dc51cf 100644 --- a/docs/src/content/docs/reference/configuration.mdx +++ b/docs/src/content/docs/reference/configuration.mdx @@ -411,6 +411,16 @@ When `false`, the colors provided by the active syntax highlighting theme are us When using custom themes and setting this to `true`, you must provide at least one dark and one light theme to ensure proper color contrast. ::: +### `pagefind` + +**type:** `boolean` +**default:** `true` + +Define whether Starlight’s default site search provider [Pagefind](https://pagefind.app/) is enabled. + +Set to `false` to disable indexing your site with Pagefind. +This will also hide the default search UI if in use. + ### `head` **type:** [`HeadConfig[]`](#headconfig) diff --git a/docs/src/content/docs/reference/overrides.md b/docs/src/content/docs/reference/overrides.md index 9bd6cc9cdad..fd4bc5d4750 100644 --- a/docs/src/content/docs/reference/overrides.md +++ b/docs/src/content/docs/reference/overrides.md @@ -234,6 +234,10 @@ The default implementation includes logic for rendering logos defined in Starlig Component used to render Starlight’s search UI. The default implementation includes the button in the header and the code for displaying a search modal when it is clicked and loading [Pagefind’s UI](https://pagefind.app/). +When [`pagefind`](/reference/configuration/#pagefind) is disabled, the default search component will not be rendered. +However, if you override `Search`, your custom component will always be rendered even if the `pagefind` configuration option is `false`. +This allows you to add UI for alternative search providers when disabling Pagefind. + #### `SocialIcons` **Default component:** [`SocialIcons.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/SocialIcons.astro) diff --git a/packages/starlight/components/Header.astro b/packages/starlight/components/Header.astro index 51bf9a0834f..7042a800de6 100644 --- a/packages/starlight/components/Header.astro +++ b/packages/starlight/components/Header.astro @@ -1,4 +1,5 @@ --- +import config from 'virtual:starlight/user-config'; import type { Props } from '../props'; import { @@ -8,6 +9,12 @@ import { SocialIcons, ThemeSelect, } from 'virtual:starlight/components'; + +/** + * Render the `Search` component if Pagefind is enabled or the default search component has been overridden. + */ +const shouldRenderSearch = + config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro'; ---
@@ -15,7 +22,7 @@ import {
- + {shouldRenderSearch && }