From 854a9b9df08f6b1b4b04babaa4382a0e5642a345 Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Mon, 5 Jun 2023 10:34:35 +0900 Subject: i18n(ja): Update getting-started.mdx --- docs/src/content/docs/ja/getting-started.mdx | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/src/content/docs/ja/getting-started.mdx b/docs/src/content/docs/ja/getting-started.mdx index 0a7a6dcf..23fc7d0b 100644 --- a/docs/src/content/docs/ja/getting-started.mdx +++ b/docs/src/content/docs/ja/getting-started.mdx @@ -11,7 +11,9 @@ Starlightはまだ開発の初期段階にあります。何か不具合を見 ## 新しいプロジェクトを作成する -Starlightは、オールインワンのフレームワークである[Astro](https://astro.build)の上に構築されています。次のコマンドにより、Astro + Starlightの新しいプロジェクトを作成できます。 +Starlightは、[Astro](https://astro.build)の上に構築された、フル機能のドキュメント向けテーマです。 + +以下のコマンドにより、Astro + Starlightの新しいプロジェクトを作成できます。 @@ -40,7 +42,7 @@ yarn create astro --template starlight -これにより、サイトに必要なすべてのファイルと設定が含まれた、新しいプロジェクトディレクトリが作成されます。 +これにより、サイトに必要なすべてのファイルと設定が含まれた、新しい[プロジェクトディレクトリ](/ja/guides/project-structure/)が作成されます。 :::tip[試してみよう] Starlightをブラウザで試すには、[StackBlitzでテンプレートを開きます](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)。 @@ -48,11 +50,24 @@ Starlightをブラウザで試すには、[StackBlitzでテンプレートを開 ## Starlightでコンテンツを作成する -Starlightでは、MarkdownとMDXでコンテンツを作成できます。 +以上で、Starlightに新しいコンテンツを追加したり、既存のファイルを持ち込んだりする準備ができました！ + +### ファイルフォーマット + +Starlightでは、MarkdownとMDXでコンテンツを作成できます。（Markdocのサポートは、実験的な[AstroのMarkdocインテグレーション](https://docs.astro.build/ja/guides/integrations-guide/markdoc/)をインストールして追加できます。） + +### ページの追加 + +`src/content/docs/`に`.md`または`.mdx`ファイルを作成して、サイトに新しいページを自動で追加できます。ファイルを整理するためにサブフォルダを追加し、複数のパスセグメントを作成することもできます。 + +```js +`src/content/docs/hello-world.md` -> `your-site/hello-world` +`src/content/docs/guides/faq.md` -> `your-site/guides/faq` +``` -`src/content/docs/`に`.md`または`.mdx`ファイルを作成して、新しいページを追加します。たとえば、`src/content/docs/hello-world.md`は、サイトの`/hello-world`からアクセスできます。 +### 型安全なフロントマター -Starlightのページは、ページの表示方法を制御するための、共通のフロントマタープロパティを認識します。 +Starlightのページは、ページの表示方法を制御するための、カスタマイズ可能な[共通のフロントマタープロパティ](/ja/reference/frontmatter/)を認識します。 ```md --- @@ -65,6 +80,6 @@ description: これはStarlightで作成されたサイトのページです ## Starlightサイトをデプロイする -Starlightサイトの作成とカスタマイズが完了したら、お好みのウェブサーバーやホスティングプラットフォームにデプロイできます。Astroには、Netlify、Vercel、GitHub Pagesなど、人気のホスティングプラットフォームへのサポートが組み込まれているため、簡単なコマンドをいくつか実行するだけでウェブサイトをデプロイできます。 +Starlightサイトの作成とカスタマイズが完了したら、Netlify、Vercel、GitHub Pages、その他多くのお好みのウェブサーバーやホスティングプラットフォームにデプロイできます。 [Astroサイトのデプロイについては、Astroのドキュメントを参照してください。](https://docs.astro.build/ja/guides/deploy/) -- cgit From f59caba955266bb36906a282a1c2cc4bdec00cd0 Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Mon, 5 Jun 2023 15:50:49 +0900 Subject: i18n(ja): Add project-structure.mdx --- .../content/docs/ja/guides/project-structure.mdx | 48 ++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/src/content/docs/ja/guides/project-structure.mdx diff --git a/docs/src/content/docs/ja/guides/project-structure.mdx b/docs/src/content/docs/ja/guides/project-structure.mdx new file mode 100644 index 00000000..78fc6778 --- /dev/null +++ b/docs/src/content/docs/ja/guides/project-structure.mdx @@ -0,0 +1,48 @@ +--- +title: ディレクトリ構成 +description: Starlightプロジェクトでファイルをどのように配置するかについて学びます。 +--- + +このガイドでは、Starlightプロジェクトの構成と、プロジェクト内のさまざまなファイルの役割について説明します。 + +Starlightプロジェクトは、基本的に他のAstroプロジェクトと同じファイル・ディレクトリ構成に従います。詳細については、[Astroのディレクトリ構成のドキュメント](https://docs.astro.build/ja/core-concepts/project-structure/)を参照してください。 + +## ファイルとディレクトリ + +- `astro.config.mjs` — Astroの設定ファイルで、ここにStarlightのインテグレーションや設定を記述します。 +- `src/content/config.ts` — コンテンツコレクションの設定ファイルで、Starlightのフロントマタースキーマをプロジェクトに追加します。 +- `src/content/docs/` — コンテンツのファイルが置かれます。Starlightは、このディレクトリ内の各`.md`、`.mdx`、`.mdoc`ファイルを、サイトのページへと変換します。 +- `src/content/i18n/`（任意） — [国際化](/ja/guides/i18n/)をサポートするための翻訳データが置かれます。 +- `src/` — プロジェクトの他のソースコードやファイル（コンポーネント、スタイル、画像など）が置かれます。 +- `public/` — Astroによって処理されない静的アセット（フォント、ファビコン、PDFなど）が置かれます。 + +## プロジェクトの中身の例 + +Starlightプロジェクトのディレクトリは、次のようになります。 + +import FileTree from '../../../../components/file-tree.astro'; + + + +- public/ + - favicon.svg +- src/ + - assets/ + - logo.svg + - screenshot.jpg + - components/ + - CustomButton.astro + - InteractiveWidget.jsx + - content/ + - docs/ + - guides/ + - 01-getting-started.md + - 02-advanced.md + - index.mdx + - config.ts + - env.d.ts +- astro.config.mjs +- package.json +- tsconfig.json + + -- cgit From a4e2ebd3372916814ad447154a62fd870904afde Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Mon, 5 Jun 2023 21:13:38 +0900 Subject: i18n(ja): Update configuration.md --- docs/src/content/docs/ja/reference/configuration.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/src/content/docs/ja/reference/configuration.md b/docs/src/content/docs/ja/reference/configuration.md index 65501ed9..20bf64e7 100644 --- a/docs/src/content/docs/ja/reference/configuration.md +++ b/docs/src/content/docs/ja/reference/configuration.md @@ -5,6 +5,21 @@ description: Starlightがサポートするすべての設定オプションの ## `starlight`インテグレーションの設定 +Starlightは[Astro](https://astro.build)ウェブフレームワークの上に構築されたインテグレーションです。Astroの`astro.config.mjs`設定ファイル内でプロジェクトの設定をおこないます。 + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; +export default defineConfig({ + integrations: [ + starlight({ + title: "私の楽しいドキュメントサイト", + }), + ], +}); +``` + 以下のオプションを`starlight`インテグレーションに設定できます。 ### `title`（必須） -- cgit From 78d6b630bf309a687ee92a48b86a560ddec273d5 Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Mon, 5 Jun 2023 21:32:11 +0900 Subject: components --- docs/src/content/docs/ja/guides/components.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/src/content/docs/ja/guides/components.mdx b/docs/src/content/docs/ja/guides/components.mdx index c2a3f63d..617307c1 100644 --- a/docs/src/content/docs/ja/guides/components.mdx +++ b/docs/src/content/docs/ja/guides/components.mdx @@ -5,9 +5,11 @@ description: StarlightにおけるMDXでのコンポーネントの利用。 コンポーネントにより、UI やスタイリングの一部を一貫性を保って簡単に再利用できます。例として、リンクカードやYouTubeの埋め込みなどが考えられます。Starlightは[MDX](https://mdxjs.com/)ファイルでのコンポーネントの使用をサポートしており、すぐに使える一般的なコンポーネントもいくつか提供しています。 +[コンポーネントの作り方について、詳しくはAstroドキュメントを参照してください](https://docs.astro.build/ja/core-concepts/astro-components/)。 + ## コンポーネントを使う -コンポーネントは、MDXファイルにインポートしてJSXタグとして呼び出すことで使用できます。HTMLタグのように見えますが、`import`文の名前と同じ大文字で始まります。 +コンポーネントは、MDXファイルにインポートしてJSXタグとしてレンダリングすることで使用できます。HTMLタグのように見えますが、`import`文の名前と同じ大文字で始まります。 ```mdx --- @@ -25,11 +27,11 @@ import AnotherComponent from '../../components/AnotherComponent.astro'; ``` -StarlightはAstroの上で動作しているため、どのUIフレームワークで作成されたコンポーネントでもMDXファイルで使用できます。[MDXでのコンポーネントの使用](https://docs.astro.build/ja/guides/markdown-content/#using-components-in-mdx)について、詳しくはAstroドキュメントを参照してください。 +StarlightはAstro製であるため、[サポート対象のUIフレームワーク（React、Preact、Svelte、Vue、Solid、Lit、Alpine）](https://docs.astro.build/ja/core-concepts/framework-components/)で作成されたコンポーネントであればMDXファイルで使用できます。[MDXでのコンポーネントの使用](https://docs.astro.build/ja/guides/markdown-content/#using-components-in-mdx)について、詳しくはAstroドキュメントを参照してください。 ## 組み込みのコンポーネント -Starlightは、一般的なドキュメントのユースケースに対して組み込みのコンポーネントを提供しています。これらのコンポーネントは、`@astrojs/starlight/components`パッケージから利用できます。 +Starlightは、一般的なドキュメントのユースケースに対して組み込みのコンポーネントをいくつか提供しています。これらのコンポーネントは、`@astrojs/starlight/components`パッケージから利用できます。 ### タブ -- cgit From 1b56f62159d46f21c1a98616226526eab010bbd6 Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Mon, 5 Jun 2023 22:26:48 +0900 Subject: i18n --- docs/src/content/docs/ja/guides/i18n.mdx | 46 +++++++++++++++++++++++++------- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/docs/src/content/docs/ja/guides/i18n.mdx b/docs/src/content/docs/ja/guides/i18n.mdx index e0be28de..036d42cb 100644 --- a/docs/src/content/docs/ja/guides/i18n.mdx +++ b/docs/src/content/docs/ja/guides/i18n.mdx @@ -45,7 +45,7 @@ Starlightは、ルーティング、フォールバックコンテンツ、右 `defaultLocale`はフォールバックコンテンツとUIラベルに使用されるため、コンテンツを最初に書く可能性が最も高い言語、またはすでにコンテンツがある言語を選択してください。 -2. `src/content/docs/`に各言語のディレクトリを作成します。たとえばステップ1で示した構成を仮定すると、次のようになります。 +2. `src/content/docs/`に各言語のディレクトリを作成します。たとえば上で示した構成に対しては、以下のフォルダを作成します。 @@ -58,7 +58,9 @@ Starlightは、ルーティング、フォールバックコンテンツ、右 -3. これで各言語のディレクトリにコンテンツ用のファイルを作成できるようになりました。言語間でページを対応させるために、同じページには同じファイル名を使用します。たとえば、`ar/index.md`と`en/index.md`は、アラビア語版と英語版のホームページをそれぞれ表わします。 +3. これで各言語のディレクトリにコンテンツ用のファイルを追加できるようになりました。言語間でページを関連付けるために、同じページには同じファイル名を使用してください。フォールバックコンテンツや翻訳に関する通知など、Starlightのi18n機能をフル活用しましょう。 + + たとえば、`ar/index.md`と`en/index.md`は、アラビア語版と英語版のホームページをそれぞれ表わします。 ### ルートロケールを使用する @@ -91,7 +93,7 @@ export default defineConfig({ }); ``` -`root`ロケールを使用する場合は、言語専用のフォルダではなく、`src/content/docs/`にその言語のページを直接配置します。たとえば上記の設定を使用した場合、英語と中国語のホームページ用ファイルは次のようになります。 +`root`ロケールを使用する場合は、言語専用のフォルダではなく、`src/content/docs/`にその言語のページを直接保存します。たとえば上記の設定を使用した場合、英語と中国語のホームページ用ファイルは次のようになります。 @@ -106,23 +108,47 @@ export default defineConfig({ #### 単一言語のサイト -サイトの言語が1つだけの場合は、その言語をルートロケールに設定できます。これにより、Starlightのデフォルト言語（英語）を上書きできますが、言語選択機能などの他の国際化機能は有効化されません。 +デフォルトでは、Starlightは単一言語（英語）のサイトです。他の言語で単一言語のサイトを作成するには、その言語を`locales`において`root`に設定します。 + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; +export default defineConfig({ + integrations: [ + starlight({ + title: '私のドキュメント', + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +これにより、言語選択機能などの他の国際化機能は有効化せずに、Starlightのデフォルト言語を上書きできます。 ## フォールバックコンテンツ -Starlightは、すべての言語で同等のページが作成されることを想定しています。たとえば`en/about.md`ファイルがある場合、サポートする他の言語もそれぞれ`about.md`を作成する必要があります。 +Starlightは、すべての言語で同等のページが作成されることを想定しています。たとえば`en/about.md`ファイルがある場合、サポートする他の言語でもそれぞれ`about.md`を作成してください。これにより、まだ翻訳されていないページに対して、Starlightが自動的にフォールバックコンテンツを提供できるようになります。 -ある言語の翻訳がまだである場合、Starlightはそのページのコンテンツを（`defaultLocale`で設定する）デフォルト言語で表示します。たとえば、概要（about）ページのフランス語版をまだ作成していない場合、デフォルト言語が英語であれば、`/fr/about`を訪れた人は英語のコンテンツを見ることになります。これにより、まずデフォルト言語にコンテンツを追加し、そして翻訳者が時間を掛けて徐々に翻訳していくことが可能となります。 +ある言語の翻訳がまだである場合、Starlightはそのページのコンテンツを（`defaultLocale`で設定する）デフォルト言語で表示します。たとえば、概要（about）ページのフランス語版をまだ作成していない場合、デフォルト言語が英語であれば、`/fr/about`を訪れた人には未翻訳であるという通知とともに英語のコンテンツが表示されます。これにより、まずデフォルト言語にコンテンツを追加し、そして翻訳者が時間を掛けて徐々に翻訳していくことが可能となります。 ## StarlightのUIを翻訳する -StarlightのデフォルトUIの一部はテキストラベルを必要とします。たとえば、このページの目次には「目次」という日本語の見出しがあります。これらのラベルを可能な限り多くの言語で提供することを目指していますが、現在は英語、ドイツ語、日本語、スペイン語のみをサポートしています。 +Starlightでは、読者が選択した言語でサイト全体を体験できるように、翻訳されたコンテンツファイルをホストするだけでなく、デフォルトUIの文字列（たとえば目次に表示されている「目次」という見出し）も翻訳できるようになっています。 + +英語、ドイツ語、日本語、ポルトガル語、スペイン語の翻訳済みUI文字列がすでに用意されていますが、[デフォルト言語をさらに追加するための貢献](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md)も歓迎します。 `18n`データコレクションを使用すると、サポートしたい言語の翻訳を追加したり、デフォルトのラベルを上書きしたりできます。 1. 設定がまだであれば、`src/content/config.ts`で`i18n`データコレクションを設定します。 ```js + // src/content/config.ts import { defineCollection } from 'astro:content'; import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; @@ -132,7 +158,7 @@ StarlightのデフォルトUIの一部はテキストラベルを必要としま }; ``` -2. StarlightのUIを翻訳したいロケールごとに、JSONファイルを`src/content/i18n/`に作成します。たとえば、以下ではアラビア語と簡体字中国語の翻訳ファイルを追加しています。 +2. UI文字列を追加で翻訳したいロケールごとに、`src/content/i18n/`にJSONファイルを作成します。たとえば、以下ではアラビア語と簡体字中国語の翻訳ファイルを追加しています。 @@ -144,7 +170,9 @@ StarlightのデフォルトUIの一部はテキストラベルを必要としま -3. 翻訳したいキーに対応する翻訳を、JSONファイルに追加します。英語のデフォルトを参考にしながら翻訳を進めてください。 +3. 翻訳したいキーに対応する翻訳を、JSONファイルに追加します。キーは英語のままとし、値のみを翻訳します（例: `"search.label": "Buscar"`）。 + + 以下は、Starlightが英語版のデフォルトとして使用している文字列です。 ```json { -- cgit From 8c55223e8c41c9dfbedecb1e4f0cde605b24925e Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Mon, 5 Jun 2023 22:32:14 +0900 Subject: Fix indentation in i18n.mdx --- docs/src/content/docs/guides/i18n.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/i18n.mdx b/docs/src/content/docs/guides/i18n.mdx index 90dea6a7..ff0a760e 100644 --- a/docs/src/content/docs/guides/i18n.mdx +++ b/docs/src/content/docs/guides/i18n.mdx @@ -61,7 +61,7 @@ Starlight provides built-in support for multilingual sites, including routing, f 3. You can now add content files in your language directories. Use the same file name to associate pages across languages and take advantage of Starlight’s full set of i18n features, including fallback content, translation notices, and more. -For example, create `ar/index.md` and `en/index.md` to represent the homepage for Arabic and English respectively. + For example, create `ar/index.md` and `en/index.md` to represent the homepage for Arabic and English respectively. ### Use a root locale -- cgit From 508beed8e9094d7943a4812f9a1159cb0950c958 Mon Sep 17 00:00:00 2001 From: Houston (Bot) Date: Mon, 5 Jun 2023 06:52:55 -0700 Subject: [ci] release (#142) Co-authored-by: github-actions[bot] --- .changeset/angry-dragons-flash.md | 5 ----- packages/starlight/CHANGELOG.md | 6 ++++++ packages/starlight/package.json | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) delete mode 100644 .changeset/angry-dragons-flash.md diff --git a/.changeset/angry-dragons-flash.md b/.changeset/angry-dragons-flash.md deleted file mode 100644 index d617e045..00000000 --- a/.changeset/angry-dragons-flash.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"@astrojs/starlight": minor ---- - -Release v0.1.0 diff --git a/packages/starlight/CHANGELOG.md b/packages/starlight/CHANGELOG.md index a14ba86c..68e64238 100644 --- a/packages/starlight/CHANGELOG.md +++ b/packages/starlight/CHANGELOG.md @@ -1,5 +1,11 @@ # @astrojs/starlight +## 0.1.0 + +### Minor Changes + +- [`43f3a02`](https://github.com/withastro/starlight/commit/43f3a024d6903072780f158dd95fb04b9f678535) Thanks [@delucis](https://github.com/delucis)! - Release v0.1.0 + ## 0.0.19 ### Patch Changes diff --git a/packages/starlight/package.json b/packages/starlight/package.json index c586dd58..0806e06e 100644 --- a/packages/starlight/package.json +++ b/packages/starlight/package.json @@ -1,6 +1,6 @@ { "name": "@astrojs/starlight", - "version": "0.0.19", + "version": "0.1.0", "description": "Build beautiful, high-performance documentation websites with Astro", "scripts": {}, "keywords": [ -- cgit From 7c0cae672ff0dd359a02a6e9ff5d168d61d7a066 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Mon, 5 Jun 2023 15:55:01 +0200 Subject: Bump starter template dep --- examples/basics/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/basics/package.json b/examples/basics/package.json index 4be1d254..f7e293bb 100644 --- a/examples/basics/package.json +++ b/examples/basics/package.json @@ -11,7 +11,7 @@ "astro": "astro" }, "dependencies": { - "@astrojs/starlight": "^0.0.18", + "@astrojs/starlight": "^0.1.0", "astro": "^2.5.0" } } -- cgit From f5d6a3d3307fc13b61189c8740ebedf7d650e0a9 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 18:57:47 +0200 Subject: Internationalization in French is here! --- docs/astro.config.mjs | 9 +- .../src/content/docs/fr-fr/environmental-impact.md | 135 +++++++++ docs/src/content/docs/fr-fr/getting-started.mdx | 86 ++++++ .../content/docs/fr-fr/guides/authoring-content.md | 209 +++++++++++++ docs/src/content/docs/fr-fr/guides/components.mdx | 111 +++++++ docs/src/content/docs/fr-fr/guides/i18n.mdx | 201 +++++++++++++ .../docs/fr-fr/guides/project-structure.mdx | 48 +++ docs/src/content/docs/fr-fr/index.mdx | 44 +++ .../content/docs/fr-fr/reference/configuration.md | 326 +++++++++++++++++++++ .../content/docs/fr-fr/reference/frontmatter.md | 119 ++++++++ 10 files changed, 1285 insertions(+), 3 deletions(-) create mode 100644 docs/src/content/docs/fr-fr/environmental-impact.md create mode 100644 docs/src/content/docs/fr-fr/getting-started.mdx create mode 100644 docs/src/content/docs/fr-fr/guides/authoring-content.md create mode 100644 docs/src/content/docs/fr-fr/guides/components.mdx create mode 100644 docs/src/content/docs/fr-fr/guides/i18n.mdx create mode 100644 docs/src/content/docs/fr-fr/guides/project-structure.mdx create mode 100644 docs/src/content/docs/fr-fr/index.mdx create mode 100644 docs/src/content/docs/fr-fr/reference/configuration.md create mode 100644 docs/src/content/docs/fr-fr/reference/frontmatter.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 076ad398..b15e21fc 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -44,6 +44,7 @@ export default defineConfig({ de: { label: 'Deutsch', lang: 'de' }, es: { label: 'Español', lang: 'es' }, ja: { label: '日本語', lang: 'ja' }, + "fr-fr": { label: 'Français', lang: 'fr-fr' }, }, sidebar: [ { @@ -52,23 +53,24 @@ export default defineConfig({ de: 'Beginne hier', es: 'Comienza aqui', ja: 'ここからはじめる', + "fr-fr": 'Commencez ici', }, items: [ { label: 'Getting Started', link: 'getting-started', - translations: { es: "Empezando", ja: '入門' }, + translations: { es: "Empezando", ja: '入門', "fr-fr": 'Mise en route' }, }, { label: 'Environmental Impact', link: 'environmental-impact', - translations: { es: "Documentación ecológica", ja: '環境への負荷' }, + translations: { es: "Documentación ecológica", ja: '環境への負荷', "fr-fr": 'Impact environnemental' }, }, ], }, { label: 'Guides', - translations: { de: 'Anleitungen', es: 'Guías', ja: 'ガイド' }, + translations: { de: 'Anleitungen', es: 'Guías', ja: 'ガイド', "fr-fr": 'Guides' }, autogenerate: { directory: 'guides' }, }, { @@ -77,6 +79,7 @@ export default defineConfig({ de: 'Referenz', es: 'Referencias', ja: 'リファレンス', + "fr-fr": 'Référence', }, autogenerate: { directory: 'reference' }, }, diff --git a/docs/src/content/docs/fr-fr/environmental-impact.md b/docs/src/content/docs/fr-fr/environmental-impact.md new file mode 100644 index 00000000..f9c8c919 --- /dev/null +++ b/docs/src/content/docs/fr-fr/environmental-impact.md @@ -0,0 +1,135 @@ +--- +title: Documents écologiques +description: Découvrez comment Starlight peut vous aider à créer des sites de documentation plus écologiques et à réduire votre empreinte carbone. +--- + +Les estimations de l'impact climatique de l'industrie du web varient entre [2 %][sf] et [4 % des émissions mondiales de carbone][bbc], ce qui équivaut à peu près aux émissions de l'industrie du transport aérien. +Le calcul de l'impact écologique d'un site web repose sur de nombreux facteurs complexes, mais ce guide contient quelques conseils pour réduire l'empreinte écologique de votre site documentaire. + +La bonne nouvelle, c'est que le choix de Starlight est un excellent début. +Selon le Website Carbon Calculator, ce site est [plus propre que 99 % des pages web testées][sl-carbon], produisant 0,01 g de CO₂ par page visitée. + +## Poids de la page + +Plus une page web transfère de données, plus elle nécessite de ressources énergétiques. +En avril 2023, la page web médiane demandait à l'utilisateur de télécharger plus de 2 000 Ko selon les [données de l'archive HTTP][http]. + +Starlight construit des pages aussi légères que possible. +Par exemple, lors de sa première visite, un utilisateur téléchargera moins de 50 Ko de données compressées, soit seulement 2,5 % de la médiane des archives HTTP. +Avec une bonne stratégie de mise en cache, les navigations suivantes peuvent télécharger jusqu'à 10 Ko. + +### Images + +Bien que Starlight fournisse une bonne base de référence, les images que vous ajoutez à vos pages de documentation peuvent rapidement augmenter le poids de vos pages. +Starlight utilise le [support d'actifs optimisés][assets] d'Astro pour optimiser les images locales dans vos fichiers Markdown et MDX. + +### Composants d'interface utilisateur + +Les composants construits avec des frameworks d'interface utilisateur tels que React ou Vue peuvent facilement ajouter de grandes quantités de JavaScript à une page. +Starlight étant construit sur Astro, les composants de ce type chargent **zéro JavaScript côté client par défaut** grâce à [Astro Islands][islands]. + +### Mise en cache + +La mise en cache est utilisée pour contrôler la durée pendant laquelle un navigateur stocke et réutilise les données qu'il a déjà téléchargées. +Une bonne stratégie de mise en cache permet à l'utilisateur d'obtenir un nouveau contenu dès qu'il est modifié, tout en évitant de télécharger inutilement le même contenu à plusieurs reprises lorsqu'il n'a pas changé. + +La façon la plus courante de configurer la mise en cache est d'utiliser l'en-tête HTTP [`Cache-Control`][cache]. +Lorsque vous utilisez Starlight, vous pouvez définir une longue durée de mise en cache pour tout ce qui se trouve dans le répertoire `/_astro/`. +Ce répertoire contient des fichiers CSS, JavaScript, et d'autres actifs intégrés qui peuvent être mis en cache pour toujours, réduisant ainsi les téléchargements inutiles : + +``` +Cache-Control: public, max-age=604800, immutable +``` + +La configuration de la mise en cache dépend de votre hébergeur. Par exemple, Vercel applique cette stratégie de mise en cache pour vous sans configuration nécessaire, tandis que vous pouvez définir des [en-têtes personnalisés pour Netlify][ntl-headers] en ajoutant un fichier `public/_headers` à votre projet : + +``` +/_astro/* + Cache-Control: public + Cache-Control: max-age=604800 + Cache-Control: immutable +``` + +[cache]: https://csswizardry.com/2019/03/cache-control-for-civilians/ +[ntl-headers]: https://docs.netlify.com/routing/headers/ + +## Consommation d'énergie + +La façon dont une page web est construite peut avoir un impact sur la puissance nécessaire pour fonctionner sur l'appareil d'un utilisateur. +En utilisant un minimum de JavaScript, Starlight réduit la puissance de traitement dont le téléphone, la tablette ou l'ordinateur d'un utilisateur a besoin pour charger et afficher les pages. + +Soyez vigilant lorsque vous ajoutez des fonctionnalités telles que des scripts de suivi analytique ou des contenus à forte teneur en JavaScript, comme des vidéos intégrées, car ils peuvent augmenter la consommation d'énergie de la page. +Si vous avez besoin d'analyses, envisagez de choisir une option légère comme [Cabin][cabin], [Fathom][fathom], ou [Plausible][plausible]. +Les vidéos intégrées comme celles de YouTube et de Vimeo peuvent être améliorées en attendant de [charger la vidéo lors de l'interaction avec l'utilisateur][lazy-video]. +Des paquets comme [`astro-embed`][embed] peuvent aider pour les services communs. + +:::tip[Le saviez-vous ?] +L'analyse et la compilation de JavaScript est l'une des tâches les plus coûteuses pour les navigateurs. +Par rapport au rendu d'une image JPEG de même taille, [le traitement de JavaScript peut prendre plus de 30 fois plus de temps][coût-de-js]. +::: + +[cabin]: https://withcabin.com/ +[fathom]: https://usefathom.com/ +[plausible]: https://plausible.io/ +[lazy-video]: https://web.dev/iframe-lazy-loading/ +[embed]: https://www.npmjs.com/package/astro-embed +[cost-of-js]: https://medium.com/dev-channel/the-cost-of-javascript-84009f51e99e + +## Hébergement + +Le lieu d'hébergement d'une page web peut avoir un impact important sur le degré de respect de l'environnement de votre site de documentation. +Les centres de données et les fermes de serveurs peuvent avoir un impact écologique important, notamment en raison de leur consommation élevée d'électricité et de leur utilisation intensive de l'eau. + +Le choix d'un hébergeur utilisant des énergies renouvelables se traduira par une réduction des émissions de carbone pour votre site. Le [Green Web Directory][gwb] est un outil qui peut vous aider à trouver des hébergeurs. + +[gwb]: https://www.thegreenwebfoundation.org/directory/ + +## Comparaisons + +Curieux de savoir comment les autres frameworks de documentation se comparent ? +Ces tests avec le [Website Carbon Calculator][wcc] comparent des pages similaires construites avec différents outils. + +| Framework | CO₂ par page visitée | +| --------------------------- | ------------------ | +| [Starlight][sl-carbon] | 0.01g | +| [VitePress][vp-carbon] | 0.05g | +| [Sphinx][sx-carbon] | 0.07g | +| [MkDocs][mk-carbon] | 0.10g | +| [Nextra][nx-carbon] | 0.11g | +| [Docusaurus][ds-carbon] | 0.24g | +| [Read the Docs][rtd-carbon] | 0.24g | +| [GitBook][gb-carbon] | 0.71g | + +Données collectées le 14 mai 2023. Cliquez sur un lien pour voir les chiffres actualisés. + +[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/ +[sx-carbon]: https://www.websitecarbon.com/website/sphinx-doc-org-en-master-usage-quickstart-html/ +[mk-carbon]: https://www.websitecarbon.com/website/mkdocs-org-getting-started/ +[nx-carbon]: https://www.websitecarbon.com/website/nextra-site-docs-docs-theme-start/ +[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/ + +## Plus de ressources + +### Outils + +- [Website Carbon Calculator][wcc] +- [Ecograder](https://ecograder.com/) +- [WebPageTest Carbon Control](https://www.webpagetest.org/carbon-control/) +- [Ecoping](https://ecoping.earth/) + +### Articles et discussions + +- [“Building a greener web”](https://youtu.be/EfPoOt7T5lg), conférence de Michelle Barker +- [“Sustainable Web Development Strategies Within An Organization”](https://www.smashingmagazine.com/2022/10/sustainable-web-development-strategies-organization/), article par Michelle Barker +- [“A sustainable web for everyone”](https://2021.stateofthebrowser.com/speakers/tom-greenwood/), conférence de Tom Greenwood +- [“How Web Content Can Affect Power Usage”](https://webkit.org/blog/8970/how-web-content-can-affect-power-usage/), article de Benjamin Poulain et Simon Fraser + +[sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/ +[bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think +[http]: https://httparchive.org/reports/state-of-the-web +[assets]: https://docs.astro.build/en/guides/assets/ +[islands]: https://docs.astro.build/en/concepts/islands/ +[wcc]: https://www.websitecarbon.com/ diff --git a/docs/src/content/docs/fr-fr/getting-started.mdx b/docs/src/content/docs/fr-fr/getting-started.mdx new file mode 100644 index 00000000..383e7073 --- /dev/null +++ b/docs/src/content/docs/fr-fr/getting-started.mdx @@ -0,0 +1,86 @@ +--- +title: Mise en route +description: Apprenez à créer votre prochain site de documentation avec Starlight by Astro. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +:::caution[Work in progress] +Starlight est en début de développement. +Si vous trouvez quelque chose qui ne fonctionne pas, [ouvrez une issue sur GitHub](https://github.com/withastro/starlight/issues/new/choose) ou faites-le nous savoir sur [Discord](https://astro.build/chat). +::: + +## Créer un nouveau projet + +Starlight est un thème de documentation complet construit sur le framework [Astro](https://astro.build). + +Vous pouvez créer un nouveau projet Astro + Starlight en utilisant la commande suivante : + + + + +```sh +# créer un nouveau projet avec npm +npm create astro@latest -- --template starlight +``` + + + + +```sh +# créer un nouveau projet avec pnpm +pnpm create astro --template starlight +``` + + + + +```sh +# créer un nouveau projet avec yarn +yarn create astro --template starlight +``` + + + + +Cela créera un nouveau [répertoire de projet](/guides/projet-structure/) avec tous les fichiers et configurations nécessaires pour votre site. + +:::tip[Voir en action] +Essayez Starlight dans votre navigateur : +[ouvrir le modèle sur StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics). +::: + +## Créer du contenu avec Starlight + +Starlight est prêt pour que vous puissiez ajouter du nouveau contenu, ou apporter vos fichiers existants ! + +### Formats de fichiers + +Starlight prend en charge la création de contenu en Markdown et MDX. (Vous pouvez ajouter la prise en charge de Markdoc en installant l'intégration expérimentale [Astro Markdoc integration](https://docs.astro.build/fr-fr/guides/integrations-guide/markdoc/).) + +### Ajouter des pages +Ajoutez automatiquement de nouvelles pages à votre site en créant des fichiers `.md` ou `.mdx` dans `src/content/docs/`. Ajoutez des sous-dossiers pour organiser vos fichiers, et pour créer plusieurs segments de chemin : + +```js +`src/content/docs/hello-world.md` -> `votre-site/hello-world` +`src/content/docs/guides/faq.md` -> `votre-site/guides/faq` +``` + +### Type-safe frontmatter + +Toutes les pages Starlight partagent un [ensemble commun de propriétés de présentation](/fr-fr/reference/frontmatter/) personnalisable pour contrôler l'apparence de la page : + +```md +--- +title: Bonjour, le monde ! +description: Ceci est une page de mon site web propulsé par Starlight. +--- +``` + +Si vous oubliez quelque chose d'important, Starlight vous le fera savoir. + +## Déployer votre site web Starlight + +Une fois que vous avez créé et personnalisé votre site Web Starlight, vous pouvez le déployer sur un serveur Web ou une plateforme d'hébergement de votre choix, y compris Netlify, Vercel, GitHub Pages et bien d'autres. + +[Pour en savoir plus sur le déploiement d'un site Astro, consultez la documentation Astro](https://docs.astro.build/fr/guides/deploy/) diff --git a/docs/src/content/docs/fr-fr/guides/authoring-content.md b/docs/src/content/docs/fr-fr/guides/authoring-content.md new file mode 100644 index 00000000..63258869 --- /dev/null +++ b/docs/src/content/docs/fr-fr/guides/authoring-content.md @@ -0,0 +1,209 @@ +--- +title: Création de contenu en Markdown +description: Un aperçu de la syntaxe Markdown prise en charge par Starlight. +--- + +Starlight prend en charge l'ensemble de la syntaxe [Markdown](https://daringfireball.net/projects/markdown/) dans les fichiers `.md` ainsi que la syntaxe frontale [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) pour définir des métadonnées telles qu'un titre et une description. + +Veillez à consulter les [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) ou les [Markdoc docs](https://markdoc.dev/docs/syntax) si vous utilisez ces formats de fichiers, car la prise en charge et l'utilisation de Markdown peuvent varier. + +## Styles en ligne + +Le texte peut être **gras**, _italique_, ou ~~barré~~. + +```md +Le texte peut être **gras**, _italique_, ou ~~barré~~. +``` + +Vous pouvez [faire un lien vers une autre page](/fr-fr/getting-started/). + +```md +Vous pouvez [faire un lien vers une autre page](/fr-fr/getting-started/). +``` + +Vous pouvez mettre en évidence le `code en ligne` à l'aide d'un astérisque. + +```md +Vous pouvez mettre en évidence le `code en ligne` à l'aide de barres de défilement. +``` + +## Images + +Les images dans Starlight utilisent la prise en charge intégrée des ressources optimisées d'Astro. + +Markdown et MDX supportent la syntaxe Markdown pour l'affichage des images qui inclut le texte alt pour les lecteurs d'écran et les technologies d'assistance. + +![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) + +```md +![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) +``` + +Les chemins d'accès relatifs aux images sont également supportés pour les images stockées localement dans votre projet. + +```md +// src/content/docs/page-1.md + +![Une fusée dans l'espace.](../../assets/images/rocket.svg) +``` + +## En-têtes + +Vous pouvez structurer le contenu à l'aide d'un titre. En Markdown, les titres sont indiqués par un nombre de `#` en début de ligne. + +### Comment structurer le contenu d'une page dans Starlight + +Starlight est configuré pour utiliser automatiquement le titre de votre page comme titre de premier niveau et inclura un titre "Aperçu" en haut de la table des matières de chaque page. Nous vous recommandons de commencer chaque page par un paragraphe de texte normal et d'utiliser des titres de page à partir de `

` : + +```md +--- +title: Guide Markdown +description: Comment utiliser Markdown dans Starlight +--- + +Cette page décrit comment utiliser Markdown dans Starlight. + +## Styles en ligne + +## Titres + +``` + +### Liens d'ancrage automatiques pour les titres + +L'utilisation de titres en Markdown vous donnera automatiquement des liens d'ancrage afin que vous puissiez accéder directement à certaines sections de votre page : + +```md +--- +title: Ma page de contenu +description: Comment utiliser les liens d'ancrage intégrés de Starlight +--- +## Introduction + +Je peux faire un lien vers [ma conclusion](#conclusion) plus bas sur la même page. + +## Conclusion + +`https://my-site.com/page1/#introduction` renvoie directement à mon Introduction. +``` + +Les titres de niveau 2 (`

`) et de niveau 3 (`

`) apparaissent automatiquement dans la table des matières de la page. + +## Asides + +Les Asides (également connus sous le nom de "callouts") sont utiles pour afficher des informations secondaires à côté du contenu principal d'une page. + +Starlight fournit une syntaxe Markdown personnalisée pour le rendu des apartés. Les blocs d'apartés sont indiqués en utilisant une paire de triples points `:::` pour envelopper votre contenu, et peuvent être de type `note`, `tip`, `caution` ou `danger`. + +Vous pouvez imbriquer n'importe quel autre type de contenu Markdown à l'intérieur d'un aparté, mais les aparté sont mieux adaptés à des morceaux de contenu courts et concis. + +### Note aside + +:::note +Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : + +```sh +npm run create astro@latest --template starlight +``` + +::: + +````md +:::note +Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : + +```sh +npm run create astro@latest --template starlight +``` + +::: +```` + +### Titres personnalisés dans les asides + +Vous pouvez spécifier un titre personnalisé pour l'aparté entre crochets après le type d'aparté, par exemple `:::tip[Le saviez-vous ?]`. + +:::tip[Le saviez-vous ?] +Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). +::: + +```md +:::tip[Le saviez-vous ?] +Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). +::: +``` + +### Plus de types pour l'aside + +Les apartés de type Attention et Danger sont utiles pour attirer l'attention de l'utilisateur sur des détails qui pourraient le faire trébucher. +Si vous les utilisez souvent, c'est peut-être aussi le signe que la chose que vous documentez gagnerait à être repensée. + +:::caution +Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). +::: + +:::danger +Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. + +- Navigation claire +- Thème de couleurs configurable par l'utilisateur +- [Support i18n](/fr-fr/guides/i18n) + +::: + +```md +:::caution +Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). +::: + +:::danger +Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. + +- Navigation claire +- Thème de couleurs configurable par l'utilisateur +- [Support i18n](/fr-fr/guides/i18n) + +::: +``` + +## Blockquotes + +> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. +> +> Les guillemets sont indiqués par un `>` au début de chaque ligne. + +```md +> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. +> +> Les guillemets sont indiqués par un `>` au début de chaque ligne. +``` + +## Code blocks + +Un bloc de code est indiqué par un bloc avec trois crochets ``` au début et à la fin. Vous pouvez indiquer le langage de programmation utilisé après les premiers crochets. + +```js +// Code Javascript avec mise en évidence de la syntaxe. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` + +````md +```js +// Code Javascript avec mise en évidence de la syntaxe. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` +```` + +```md +Les longs blocs de code d'une seule ligne ne doivent pas être enveloppés. Ils doivent défiler horizontalement s'ils sont trop longs. Cette ligne devrait être suffisamment longue pour le démontrer. +``` + +## Autres fonctionnalités courantes de Markdown + +Starlight prend en charge toutes les autres syntaxes de rédaction Markdown, telles que les listes et les tableaux. Voir [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) pour un aperçu rapide de tous les éléments de la syntaxe Markdown. diff --git a/docs/src/content/docs/fr-fr/guides/components.mdx b/docs/src/content/docs/fr-fr/guides/components.mdx new file mode 100644 index 00000000..5e1000cf --- /dev/null +++ b/docs/src/content/docs/fr-fr/guides/components.mdx @@ -0,0 +1,111 @@ +--- +title: Composants +description: Utilisation de composants dans MDX avec Starlight. +--- + +Les composants vous permettent de réutiliser facilement un élément d'interface utilisateur ou de style de manière cohérente. +Il peut s'agir par exemple d'une carte de lien ou d'une intégration YouTube. +Starlight prend en charge l'utilisation de composants dans les fichiers [MDX](https://mdxjs.com/) et fournit des composants courants que vous pouvez utiliser. + +[Pour en savoir plus sur la création de composants, consultez les Astro Docs](https://docs.astro.build/fr/core-concepts/astro-components/). + +## Utilisation d'un composant + +Vous pouvez utiliser un composant en l'important dans votre fichier MDX et en le rendant sous forme de balise JSX. +Ces balises ressemblent à des balises HTML mais commencent par une lettre majuscule correspondant au nom de votre déclaration `import` : + +```mdx +--- +# src/content/docs/index.mdx +title: Bienvenue dans ma documentation +--- + +import SomeComponent from '../../components/SomeComponent.astro'; +import AnotherComponent from '../../components/AnotherComponent.astro'; + + + + + Les composants peuvent également contenir du **contenu imbriqué**. + +``` + +Starlight étant alimenté par Astro, vous pouvez ajouter la prise en charge des composants construits avec n'importe quel [cadre d'interface utilisateur pris en charge (React, Preact, Svelte, Vue, Solid, Lit et Alpine)](https://docs.astro.build/fr/core-concepts/framework-components/) dans vos fichiers MDX. +Pour en savoir plus sur [l'utilisation de composants dans MDX](https://docs.astro.build/fr/guides/markdown-content/#using-components-in-mdx), consultez la documentation Astro. + +## Composants intégrés + +Starlight fournit quelques composants intégrés pour les cas d'utilisation courants de la documentation. +Ces composants sont disponibles dans le paquet `@astrojs/starlight/components`. + +### Onglets + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Vous pouvez afficher une interface à onglets en utilisant les composants `` et ``. +Chaque `` doit avoir un `label` à afficher aux utilisateurs. + +```mdx +import { Tabs, TabItem } from '@astrojs/starlight/components'; + + + Sirius, Vega, Betelgeuse + Io, Europa, Ganymede + +``` + +Le code ci-dessus génère les onglets suivants sur la page : + + + Sirius, Vega, Betelgeuse + Io, Europa, Ganymede + + +### Cards + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +Vous pouvez afficher du contenu dans une boîte correspondant aux styles de Starlight en utilisant le composant ``. +Enveloppez plusieurs cartes dans le composant `` pour afficher les cartes côte à côte lorsqu'il y a suffisamment d'espace. + +Une `` nécessite un `titre` et peut éventuellement inclure un attribut `icon` fixé au nom de [l'une des icônes intégrées de Starlight](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts). + +```mdx +import { Card, CardGrid } from '@astrojs/starlight/components'; + +Contenu intéressant que vous souhaitez mettre en évidence. + + + + Sirius, Vega, Betelgeuse + + + Io, Europa, Ganymede + + +``` + +Le code ci-dessus génère ce qui suit sur la page : + +Contenu intéressant que vous souhaitez mettre en évidence. + + + + Sirius, Vega, Betelgeuse + + + Io, Europa, Ganymede + + + +:::tip +Utilisez une grille de cartes sur votre page d'accueil pour afficher les principales caractéristiques de votre projet. +Ajoutez l'attribut `stagger` pour décaler verticalement la deuxième colonne de cartes et ajouter un intérêt visuel : + +```astro + + + +``` + +::: diff --git a/docs/src/content/docs/fr-fr/guides/i18n.mdx b/docs/src/content/docs/fr-fr/guides/i18n.mdx new file mode 100644 index 00000000..0bde4184 --- /dev/null +++ b/docs/src/content/docs/fr-fr/guides/i18n.mdx @@ -0,0 +1,201 @@ +--- +title: Internationalisation (i18n) +description: Apprenez à configurer votre site Starlight pour qu'il prenne en charge plusieurs langues. +--- + +import FileTree from '../../../components/file-tree.astro'; + +Starlight offre une prise en charge intégrée des sites multilingues, y compris le routage, le contenu de repli et la prise en charge complète des langues de droite à gauche (RTL). + +## Configurer i18n + +1. Indiquez à Starlight les langues que vous prenez en charge en passant `locales` et `defaultLocale` à l'intégration Starlight : + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + // Définit l'anglais comme langue par défaut pour ce site. + defaultLocale: 'en', + locales: { + // Docs en anglais dans `src/content/docs/en/` + en: { + label: 'English', + }, + // Documentation en chinois simplifié dans `src/content/docs/zh/` + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + // docs en arabe dans `src/content/docs/ar/` + ar: { + label: 'العربية', + dir: 'rtl', + }, + }, + }), + ], + }); + ``` + + Votre `defaultLocale` sera utilisé pour le contenu de repli et les étiquettes de l'interface utilisateur, donc choisissez la langue dans laquelle vous êtes le plus susceptible de commencer à écrire du contenu, ou pour laquelle vous avez déjà du contenu. + +2. Créez un répertoire pour chaque langue dans `src/content/docs/`. + Par exemple, pour la configuration montrée ci-dessus, créez les dossiers suivants : + + + + - src/ + - content/ + - docs/ + - ar/ + - en/ + - zh/ + + + +3. Vous pouvez maintenant ajouter des fichiers de contenu dans vos répertoires de langues. Utilisez le même nom de fichier pour associer les pages d'une langue à l'autre et profiter de l'ensemble des fonctionnalités i18n de Starlight, y compris le contenu de repli, les avis de traduction, etc. + + Par exemple, créez `ar/index.md` et `en/index.md` pour représenter la page d'accueil en arabe et en anglais respectivement. + +### Utiliser une racine locale + +Vous pouvez utiliser une racine locale pour servir une langue sans aucun préfixe i18n dans son chemin. Par exemple, si l'anglais est votre racine locale, le chemin d'une page en anglais ressemblera à `/about` au lieu de `/en/about`. + +Pour définir une racine locale, utilisez la clé `root` dans votre configuration `locales`. Si la racine locale est aussi la locale par défaut de votre contenu, supprimez `defaultLocale` ou donnez-lui la valeur `'root''. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + defaultLocale: 'root', // optionnel + locales: { + root: { + label: 'English', + lang: 'en', // lang est nécessaire pour les locales de la racine + }, + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Lorsque vous utilisez une locale `root`, gardez les pages pour cette langue directement dans `src/content/docs/` au lieu d'un dossier dédié à la langue. Par exemple, voici les fichiers de la page d'accueil pour l'anglais et le chinois en utilisant la configuration ci-dessus : + + + +- src/ + - content/ + - docs/ + - **index.md** + - zh/ + - **index.md** + + + +#### Sites monolingues + +Par défaut, Starlight est un site monolingue (anglais). Pour créer un site monolingue dans une autre langue, définissez-la comme `root` dans votre configuration `locales` : + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Cela vous permet de remplacer la langue par défaut de Starlight sans activer d'autres fonctions d'internationalisation pour les sites multilingues, telles que le sélecteur de langue. + +## Contenu de remplacement + +Starlight s'attend à ce que vous créiez des pages équivalentes dans toutes vos langues. Par exemple, si vous avez un fichier `en/about.md`, créez un `about.md` pour chaque autre langue que vous supportez. Cela permet à Starlight de fournir un contenu de remplacement automatique pour les pages qui n'ont pas encore été traduites. + +Si une traduction n'est pas encore disponible pour une langue, Starlight affichera aux lecteurs le contenu de cette page dans la langue par défaut (définie via `defaultLocale`). Par exemple, si vous n'avez pas encore créé de version française de votre page À propos et que votre langue par défaut est l'anglais, les visiteurs de `/fr/about` verront le contenu anglais de `/en/about` avec un avis indiquant que cette page n'a pas encore été traduite. Cela vous permet d'ajouter du contenu dans votre langue par défaut et de le traduire progressivement lorsque vos traducteurs en ont le temps. + +## Traduire l'interface utilisateur de Starlight + +En plus d'héberger des fichiers de contenu traduits, Starlight vous permet de traduire les chaînes de l'interface utilisateur par défaut (par exemple, l'en-tête "Sur cette page" dans la table des matières) afin que vos lecteurs puissent découvrir votre site entièrement dans la langue sélectionnée. + +Les chaînes d'interface utilisateur traduites en anglais, allemand, japonais, portugais et espagnol sont fournies d'office, et nous acceptons les [contributions pour ajouter d'autres langues par défaut](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). + +Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collecte de données `i18n`. + +1. Configurez la collection de données `i18n` dans `src/content/config.ts` si elle n'est pas déjà configurée : + + ```js + // src/content/config.ts + import { defineCollection } from 'astro:content'; + import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; + + export const collections = { + docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), + }; + ``` + +2. Créez un fichier JSON dans `src/content/i18n/` pour chaque locale supplémentaire pour laquelle vous voulez fournir des chaînes de traduction pour l'interface utilisateur. + Par exemple, cela ajouterait des fichiers de traduction pour l'arabe et le chinois simplifié : + + + + - src/ + - content/ + - i18n/ + - ar.json + - zh-CN.json + + + +3. Ajoutez des traductions pour les clés que vous souhaitez traduire dans les fichiers JSON. Traduire uniquement les valeurs, en laissant les clés en anglais (e.g. `"search.label": "Buscar"`). + + Il s'agit des valeurs anglaises par défaut des chaînes de caractères existantes avec lesquelles Starlight est livré : + + ```json + { + "skipLink.label": "Aller au contenu", + "search.label": "rechercher", + "search.shortcutLabel": "(Presser / pour rechercher)", + "search.cancelLabel": "Annuler", + "themeSelect.accessibleLabel": "Selectionner le thème", + "themeSelect.dark": "Dark", + "themeSelect.light": "Light", + "themeSelect.auto": "Auto", + "languageSelect.accessibleLabel": "Selectionner la langue", + "menuButton.accessibleLabel": "Menu", + "sidebarNav.accessibleLabel": "Main", + "tableOfContents.onThisPage": "Sur cette page", + "tableOfContents.overview": "Vue d'ensemble", + "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", + "page.editLink": "Editer la page", + "page.lastUpdated": "Dernière mise à jour :", + "page.previousLink": "Suivant", + "page.nextLink": "Précédent" + } + ``` diff --git a/docs/src/content/docs/fr-fr/guides/project-structure.mdx b/docs/src/content/docs/fr-fr/guides/project-structure.mdx new file mode 100644 index 00000000..cbb6855f --- /dev/null +++ b/docs/src/content/docs/fr-fr/guides/project-structure.mdx @@ -0,0 +1,48 @@ +--- +title: Structure du projet +description: Apprenez à organiser les fichiers dans votre projet Starlight. +--- + +Ce guide vous montrera comment un projet Starlight est organisé et ce que font les différents fichiers de votre projet. + +Les projets Starlight suivent généralement la même structure de fichiers et de répertoires que les autres projets Astro. Voir [la documentation sur la structure des projets Astro](https://docs.astro.build/fr/core-concepts/project-structure/) pour plus de détails. + +## Fichiers et répertoires + +- `astro.config.mjs` — Le fichier de configuration d'Astro ; inclut l'intégration et la configuration de Starlight. +- `src/content/config.ts` — Fichier de configuration des collections de contenu ; ajoute les schémas de la matière première de Starlight à votre projet. +- `src/content/docs/` — Fichiers de contenu. Starlight transforme chaque fichier `.md`, `.mdx` ou `.mdoc` de ce répertoire en une page de votre site. +- `src/content/i18n/` (optionnel) — Données de traduction pour prendre en charge l'[internationalisation](/fr-fr/guides/i18n/). +- `src/` — Autre code source et fichiers (composants, styles, images, etc.) pour votre projet. +- `public/` — Actifs statiques (polices, favicon, PDFs, etc.) qui ne seront pas traités par Astro. + +## Exemple de contenu de projet + +Un répertoire de projet Starlight peut ressembler à ceci : + +import FileTree from '../../../components/file-tree.astro'; + + + +- public/ + - favicon.svg +- src/ + - assets/ + - logo.svg + - screenshot.jpg + - components/ + - CustomButton.astro + - InteractiveWidget.jsx + - content/ + - docs/ + - guides/ + - 01-getting-started.md + - 02-advanced.md + - index.mdx + - config.ts + - env.d.ts +- astro.config.mjs +- package.json +- tsconfig.json + + diff --git a/docs/src/content/docs/fr-fr/index.mdx b/docs/src/content/docs/fr-fr/index.mdx new file mode 100644 index 00000000..71fbca0e --- /dev/null +++ b/docs/src/content/docs/fr-fr/index.mdx @@ -0,0 +1,44 @@ +--- +title: Starlight 🌟 Construire des sites de documentation avec Astro +description: Starlight vous aide à créer de magnifiques sites web de documentation très performants avec Astro. +template: splash +hero: + title: Faites briller vos documents avec Starlight + tagline: Tout ce dont vous avez besoin pour créer un excellent site web de documentation. Rapide, accessible et facile à utiliser. + image: + file: ../../../assets/hero-star.webp + actions: + - text: Mise en route + icon: right-arrow + variant: primary + link: /fr-fr/getting-started/ + - text: Voir sur GitHub + icon: external + link: https://github.com/withastro/starlight +--- + +import { CardGrid, Card } from '@astrojs/starlight/components'; +import AboutAstro from '../../components/about-astro.astro'; + + + + Comprend : Navigation dans le site, recherche, internationalisation, référencement naturel, typographie facile à lire, mise en évidence du code, mode sombre, etc. + + + Exploitez toute la puissance et les performances d'Astro. Étendez Starlight avec vos intégrations et bibliothèques Astro préférées. + + + Apportez votre langage de balisage préféré. Starlight vous offre une validation frontmatter intégrée avec la sécurité de type TypeScript. + + + Starlight est une solution de documentation complète, indépendante du cadre de travail. Étendez avec React, Vue, Svelte, Solid, et plus encore. + + + + +Astro est le framework web tout-en-un conçu pour la vitesse. +Tirez votre contenu de n'importe où et déployez-le partout, le tout alimenté par vos composants et bibliothèques d'interface utilisateur préférés. + +[En savoir plus sur Astro](https://astro.build/) + + diff --git a/docs/src/content/docs/fr-fr/reference/configuration.md b/docs/src/content/docs/fr-fr/reference/configuration.md new file mode 100644 index 00000000..4e6ab2f9 --- /dev/null +++ b/docs/src/content/docs/fr-fr/reference/configuration.md @@ -0,0 +1,326 @@ +--- +title: Référence de configuration +description: Une vue d'ensemble de toutes les options de configuration prises en charge par Starlight. +--- + +## Configuration de l'intégration `starlight` + +Starlight est une intégration construite sur le framework web [Astro](https://astro.build). Vous pouvez configurer votre projet dans le fichier de configuration Astro `astro.config.mjs` : + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: "Mon délicieux site de docs", + }), + ], +}); +``` + +Vous pouvez passer les options suivantes à l'intégration `starlight`. + +### `title` (obligatoire) + +**type:** `string` + +Définissez le titre de votre site web. Il sera utilisé dans les métadonnées et dans le titre de l'onglet du navigateur. + +### `description` + +**type:** `string` + +Définissez la description de votre site web. Utilisée dans les métadonnées partagées avec les moteurs de recherche dans la balise `` si `description` n'est pas définie dans le frontmatter d'une page. + +### `logo` + +**type:** [`LogoConfig`](#logoconfig) + +Définit une image de logo à afficher dans la barre de navigation à côté ou à la place du titre du site. Vous pouvez soit définir une seule propriété `src`, soit définir des sources d'images séparées pour `light` et `dark`. + +```js +starlight({ + logo: { + src: '/src/assets/my-logo.svg', + }, +}); +``` + +#### `LogoConfig` + +```ts +type LogoConfig = { alt?: string; replacesTitle?: boolean } & ( + | { src: string } + | { light: string; dark: string } +); +``` + +### `tableOfContents` + +**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` +**default:** `{ minHeadingLevel: 2; maxHeadingLevel: 3; }` + +Configurez la table des matières affichée à droite de chaque page. Par défaut, les titres `

` et `

` seront inclus dans cette table des matières. + +### `editLink` + +**type:** `{ baseUrl: string }` + +Permet d'activer les liens "Modifier cette page" en définissant l'URL de base qu'ils doivent utiliser. Le lien final sera `editLink.baseUrl` + le chemin de la page actuelle. Par exemple, pour permettre l'édition de pages dans le repo `withastro/starlight` sur GitHub : + +```js +starlight({ + editLink: { + baseUrl: 'https://github.com/withastro/starlight/edit/main/', + }, +}); +``` + +Avec cette configuration, une page `/introduction` aurait un lien d'édition pointant vers `https://github.com/withastro/starlight/edit/main/src/docs/introduction.md`. + +### `sidebar` + +**type:** [`SidebarGroup[]`](#sidebargroup) + +Configure les éléments de navigation de la barre latérale de votre site. + +Une barre latérale est un tableau de groupes, chacun avec un `label` pour le groupe et un tableau `items` ou un objet de configuration `autogenerate`. + +Vous pouvez définir manuellement le contenu d'un groupe en utilisant `items`, qui est un tableau pouvant inclure des liens et des sous-groupes. Vous pouvez aussi générer automatiquement le contenu d'un groupe à partir d'un répertoire spécifique de votre documentation, en utilisant `autogenerate`. + +```js +starlight({ + sidebar: [ + // Un groupe intitulé "Commencer ici" contenant deux liens. + { + label: 'Commencer ici', + items: [ + { label: 'Introduction', link: '/intro' }, + { label: 'Etapes', link: '/next-steps' }, + ], + }, + // Un groupe qui renvoie à toutes les pages du répertoire de référence. + { + label: 'Référence', + autogenerate: { directory: 'reference' }, + }, + ], +}); +``` + +#### Tri + +Les groupes de barres latérales générées automatiquement sont triés par nom de fichier et par ordre alphabétique. +Par exemple, une page générée à partir de `astro.md` apparaîtrait au-dessus de la page de `starlight.md`. + +#### Traduire les étiquettes + +Si votre site est multilingue, le `label` de chaque élément est considéré comme étant dans la locale par défaut. Vous pouvez définir une propriété `translations` pour fournir des étiquettes pour les autres langues supportées : + +```js +sidebar: [ + // Un exemple de barre latérale avec des étiquettes traduites en anglais. + { + label: 'Commencer ici', + translations: { en: 'Start here' }, + items: [ + { + label: 'Bien démarrer', + translations: { en: 'Getting Started' }, + link: '/getting-started', + }, + { + label: 'Structure du projet', + translations: { en: 'Project Structure' }, + link: '/structure', + }, + ], + }, +]; +``` + +#### `SidebarGroup` + +```ts +type SidebarGroup = + | { + label: string; + translations?: Record; + items: Array; + } + | { + label: string; + translations?: Record; + autogenerate: { + directory: string; + }; + }; +``` + +#### `LinkItem` + +```ts +interface LinkItem { + label: string; + link: string; +} +``` + +### `locales` + +**type:** `{ [dir: string]: LocaleConfig }` + +Configurez l'internationalisation (i18n) de votre site en définissant les `locales` supportées. + +Chaque entrée doit utiliser comme clé le répertoire dans lequel les fichiers de cette langue sont sauvegardés. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Site', + // Définit l'anglais comme langue par défaut pour ce site. + defaultLocale: 'en', + locales: { + // Documentations en anglais danse trouve dans `src/content/docs/en/` + en: { + label: 'English', + }, + // Documentations en Chinois simplifié se trouve dans `src/content/docs/zh/` + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + // Documentations en Arabe se trouve dans `src/content/docs/ar/` + ar: { + label: 'العربية', + dir: 'rtl', + }, + }, + }), + ], +}); +``` + +#### Options des paramètres linguistiques + +Vous pouvez définir les options suivantes pour chaque locale : + +##### `label` (obligatoire) + +**type:** `string` + +L'étiquette de cette langue à afficher aux utilisateurs, par exemple dans le sélecteur de langue. Le plus souvent, il s'agit du nom de la langue tel qu'un utilisateur de cette langue s'attendrait à le lire, par exemple `"English"`, `"العربية"`, ou `"简体中文"`. + +##### `lang` + +**type:** `string` + +La balise BCP-47 pour cette langue, par exemple `"en"`, `"ar"`, ou `"zh-CN"`. S'il n'est pas défini, le nom du répertoire de la langue sera utilisé par défaut. + +##### `dir` + +**type:** `'ltr' | 'rtl'` + +Le sens d'écriture de cette langue ; `"ltr"` pour gauche à droite (par défaut) ou `"rtl"` pour droite à gauche. + +#### Locale racine + +Vous pouvez servir la langue par défaut sans répertoire `/lang/` en définissant une locale `root` : + +```js +starlight({ + locales: { + root: { + label: 'English', + lang: 'en', + }, + fr: { + label: 'Français', + }, + }, +}); +``` + +Par exemple, cela vous permet de servir `/getting-started/` comme une route anglaise et d'utiliser `/fr/getting-started/` comme la page française équivalente. + +### `defaultLocale` + +**type:** `string` + +Définit la langue par défaut pour ce site. +La valeur doit correspondre à l'une des clés de votre objet [`locales`](#locales). +(Si votre langue par défaut est votre [root locale](#root-locale), vous pouvez sauter cette étape). + +La locale par défaut sera utilisée pour fournir un contenu de remplacement lorsque les traductions sont manquantes. + +### `social` + +**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }` + +Détails optionnels sur les comptes de médias sociaux pour ce site. L'ajout de l'un d'entre eux les affichera sous forme de liens iconiques dans l'en-tête du site. + +```js +starlight({ + social: { + discord: 'https://astro.build/chat', + github: 'https://github.com/withastro/starlight', + mastodon: 'https://m.webtoo.ls/@astro', + twitter: 'https://twitter.com/astrodotbuild', + }, +}); +``` + +### `customCss` + +**type:** `string[]` + +Fournit des fichiers CSS pour personnaliser l'aspect et la convivialité de votre site Starlight. + +Prend en charge les fichiers CSS locaux relatifs à la racine de votre projet, par exemple `'/src/custom.css'`, et les CSS que vous avez installés en tant que module npm, par exemple `'@fontsource/roboto'`. + +```js +starlight({ + customCss: ['/src/custom-styles.css', '@fontsource/roboto'], +}); +``` + +### `head` + +**type:** [`HeadConfig[]`](#headconfig) + +Ajoute des balises personnalisées au `` de votre site Starlight. +Cela peut être utile pour ajouter des analyses et d'autres scripts et ressources tiers. + +```js +starlight({ + head: [ + // Exemple : ajouter un script d'analyse Fathom tag. + { + tag: 'script', + attrs: { + src: 'https://cdn.usefathom.com/script.js', + 'data-site': 'MY-FATHOM-ID', + defer: true, + }, + }, + ], +}); +``` + +#### `HeadConfig` + +```ts +interface HeadConfig { + tag: string; + attrs?: Record; + content?: string; +} +``` diff --git a/docs/src/content/docs/fr-fr/reference/frontmatter.md b/docs/src/content/docs/fr-fr/reference/frontmatter.md new file mode 100644 index 00000000..6c64d0fe --- /dev/null +++ b/docs/src/content/docs/fr-fr/reference/frontmatter.md @@ -0,0 +1,119 @@ +--- +title: Frontmatter Reference +description: Une vue d'ensemble des champs frontmatter par défaut pris en charge par Starlight. +--- + +Vous pouvez personnaliser des pages Markdown et MDX individuelles dans Starlight en définissant des valeurs dans leur page de garde. Par exemple, une page normale peut définir les champs `title` et `description` : + +```md +--- +title: A propos de ce projet +description: En savoir plus sur le projet sur lequel je travaille. +--- + +Bienvenue sur la page "à propos" ! +``` + +## Champs de la page d'accueil + +### `title` (obligatoire) + +**type:** `string` + +Vous devez fournir un titre pour chaque page. Il sera affiché en haut de la page, dans les onglets du navigateur et dans les métadonnées de la page. + +### `description` + +**type:** `string` + +La description de la page est utilisée pour les métadonnées de la page et sera reprise par les moteurs de recherche et dans les aperçus des médias sociaux. + +### `editUrl` + +**type:** `string | boolean` + +Remplace la [configuration globale `editLink`](/fr-fr/reference/configuration/#editlink). Mettez `false` pour désactiver le lien "Editer la page" pour une page spécifique ou pour fournir une URL alternative où le contenu de cette page est éditable. + +### `head` + +**type:** [`HeadConfig[]`](/fr-fr/reference/configuration/#headconfig) + +Vous pouvez ajouter des balises supplémentaires au champ `` de votre page en utilisant le champ `head` frontmatter. Cela signifie que vous pouvez ajouter des styles personnalisés, des métadonnées ou d'autres balises à une seule page. Similaire à [l'option globale `head`](/fr-fr/reference/configuration/#head). + +```md +--- +title: A propos de nous +head: + # Utiliser une balise personnalisée + - tag: title + content: Titre personnalisé à propos de nous +--- +``` + +### `tableOfContents` + +**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` + +Remplace la [configuration globale `tableOfContents`](/fr-fr/reference/configuration/#tableofcontents). +Personnalisez les niveaux d'en-tête à inclure ou mettez `false` pour cacher la table des matières sur cette page. + +### `template` + +**type:** `'doc' | 'splash'` +**default:** `'doc'` + +Set the layout template for this page. +Pages use the `'doc'` layout by default. +Set to `'splash'` to use a wider layout without any sidebars designed for landing pages. + +### `hero` + +**type:** [`HeroConfig`](#heroconfig) + +Ajoute un composant héros en haut de la page. Fonctionne bien avec `template : splash`. + +Par exemple, cette configuration montre quelques options communes, y compris le chargement d'une image depuis votre dépôt. + +```md +--- +title: Ma page d'accueil +template: splash +hero: + title: 'Mon projet : Stellar Stuffer Sooner' + tagline: Emmenez vos affaires sur la lune et revenez-y en un clin d'œil. + image: + alt: Un logo aux couleurs vives et scintillantes + file: ../../assets/logo.png + actions: + - text: En savoir plus + link: /getting-started/ + icon: right-arrow + variant: primary + - text: Voir sur GitHub + link: https://github.com/astronaut/my-project + icon: external +--- +``` + +#### `HeroConfig` + +```ts +interface HeroConfig { + title?: string; + tagline?: string; + image?: { + alt?: string; + // Chemin relatif vers une image dans votre référentiel. + file?: string; + // HTML brut à utiliser dans l'emplacement de l'image. + // Il peut s'agir d'une balise `<img>` personnalisée ou d'une balise `<svg>` en ligne. + html?: string; + }; + actions?: Array<{ + text: string; + link: string; + variant: 'primary' | 'secondary' | 'minimal'; + icon: string; + }>; +} +``` -- cgit From 69406c4e91d0a980a2d39f4538717a7fb9669730 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 19:01:23 +0200 Subject: fr-fr to fr-FR in astro.config --- docs/astro.config.mjs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index b15e21fc..47770e54 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -44,7 +44,7 @@ export default defineConfig({ de: { label: 'Deutsch', lang: 'de' }, es: { label: 'Español', lang: 'es' }, ja: { label: '日本語', lang: 'ja' }, - "fr-fr": { label: 'Français', lang: 'fr-fr' }, + "fr-FR": { label: 'Français', lang: 'fr-FR' }, }, sidebar: [ { @@ -53,24 +53,24 @@ export default defineConfig({ de: 'Beginne hier', es: 'Comienza aqui', ja: 'ここからはじめる', - "fr-fr": 'Commencez ici', + "fr-FR": 'Commencez ici', }, items: [ { label: 'Getting Started', link: 'getting-started', - translations: { es: "Empezando", ja: '入門', "fr-fr": 'Mise en route' }, + translations: { es: "Empezando", ja: '入門', "fr-FR": 'Mise en route' }, }, { label: 'Environmental Impact', link: 'environmental-impact', - translations: { es: "Documentación ecológica", ja: '環境への負荷', "fr-fr": 'Impact environnemental' }, + translations: { es: "Documentación ecológica", ja: '環境への負荷', "fr-FR": 'Impact environnemental' }, }, ], }, { label: 'Guides', - translations: { de: 'Anleitungen', es: 'Guías', ja: 'ガイド', "fr-fr": 'Guides' }, + translations: { de: 'Anleitungen', es: 'Guías', ja: 'ガイド', "fr-FR": 'Guides' }, autogenerate: { directory: 'guides' }, }, { @@ -79,7 +79,7 @@ export default defineConfig({ de: 'Referenz', es: 'Referencias', ja: 'リファレンス', - "fr-fr": 'Référence', + "fr-FR": 'Référence', }, autogenerate: { directory: 'reference' }, }, -- cgit From 74d89b8472c3cb6c758de6f355896c6cc46386ec Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 19:06:16 +0200 Subject: fr-fr to fr-FR --- .../src/content/docs/fr-FR/environmental-impact.md | 135 +++++++++ docs/src/content/docs/fr-FR/getting-started.mdx | 86 ++++++ .../content/docs/fr-FR/guides/authoring-content.md | 209 +++++++++++++ docs/src/content/docs/fr-FR/guides/components.mdx | 111 +++++++ docs/src/content/docs/fr-FR/guides/i18n.mdx | 201 +++++++++++++ .../docs/fr-FR/guides/project-structure.mdx | 48 +++ docs/src/content/docs/fr-FR/index.mdx | 44 +++ .../content/docs/fr-FR/reference/configuration.md | 326 +++++++++++++++++++++ .../content/docs/fr-FR/reference/frontmatter.md | 119 ++++++++ .../src/content/docs/fr-fr/environmental-impact.md | 135 --------- docs/src/content/docs/fr-fr/getting-started.mdx | 86 ------ .../content/docs/fr-fr/guides/authoring-content.md | 209 ------------- docs/src/content/docs/fr-fr/guides/components.mdx | 111 ------- docs/src/content/docs/fr-fr/guides/i18n.mdx | 201 ------------- .../docs/fr-fr/guides/project-structure.mdx | 48 --- docs/src/content/docs/fr-fr/index.mdx | 44 --- .../content/docs/fr-fr/reference/configuration.md | 326 --------------------- .../content/docs/fr-fr/reference/frontmatter.md | 119 -------- 18 files changed, 1279 insertions(+), 1279 deletions(-) create mode 100644 docs/src/content/docs/fr-FR/environmental-impact.md create mode 100644 docs/src/content/docs/fr-FR/getting-started.mdx create mode 100644 docs/src/content/docs/fr-FR/guides/authoring-content.md create mode 100644 docs/src/content/docs/fr-FR/guides/components.mdx create mode 100644 docs/src/content/docs/fr-FR/guides/i18n.mdx create mode 100644 docs/src/content/docs/fr-FR/guides/project-structure.mdx create mode 100644 docs/src/content/docs/fr-FR/index.mdx create mode 100644 docs/src/content/docs/fr-FR/reference/configuration.md create mode 100644 docs/src/content/docs/fr-FR/reference/frontmatter.md delete mode 100644 docs/src/content/docs/fr-fr/environmental-impact.md delete mode 100644 docs/src/content/docs/fr-fr/getting-started.mdx delete mode 100644 docs/src/content/docs/fr-fr/guides/authoring-content.md delete mode 100644 docs/src/content/docs/fr-fr/guides/components.mdx delete mode 100644 docs/src/content/docs/fr-fr/guides/i18n.mdx delete mode 100644 docs/src/content/docs/fr-fr/guides/project-structure.mdx delete mode 100644 docs/src/content/docs/fr-fr/index.mdx delete mode 100644 docs/src/content/docs/fr-fr/reference/configuration.md delete mode 100644 docs/src/content/docs/fr-fr/reference/frontmatter.md diff --git a/docs/src/content/docs/fr-FR/environmental-impact.md b/docs/src/content/docs/fr-FR/environmental-impact.md new file mode 100644 index 00000000..f9c8c919 --- /dev/null +++ b/docs/src/content/docs/fr-FR/environmental-impact.md @@ -0,0 +1,135 @@ +--- +title: Documents écologiques +description: Découvrez comment Starlight peut vous aider à créer des sites de documentation plus écologiques et à réduire votre empreinte carbone. +--- + +Les estimations de l'impact climatique de l'industrie du web varient entre [2 %][sf] et [4 % des émissions mondiales de carbone][bbc], ce qui équivaut à peu près aux émissions de l'industrie du transport aérien. +Le calcul de l'impact écologique d'un site web repose sur de nombreux facteurs complexes, mais ce guide contient quelques conseils pour réduire l'empreinte écologique de votre site documentaire. + +La bonne nouvelle, c'est que le choix de Starlight est un excellent début. +Selon le Website Carbon Calculator, ce site est [plus propre que 99 % des pages web testées][sl-carbon], produisant 0,01 g de CO₂ par page visitée. + +## Poids de la page + +Plus une page web transfère de données, plus elle nécessite de ressources énergétiques. +En avril 2023, la page web médiane demandait à l'utilisateur de télécharger plus de 2 000 Ko selon les [données de l'archive HTTP][http]. + +Starlight construit des pages aussi légères que possible. +Par exemple, lors de sa première visite, un utilisateur téléchargera moins de 50 Ko de données compressées, soit seulement 2,5 % de la médiane des archives HTTP. +Avec une bonne stratégie de mise en cache, les navigations suivantes peuvent télécharger jusqu'à 10 Ko. + +### Images + +Bien que Starlight fournisse une bonne base de référence, les images que vous ajoutez à vos pages de documentation peuvent rapidement augmenter le poids de vos pages. +Starlight utilise le [support d'actifs optimisés][assets] d'Astro pour optimiser les images locales dans vos fichiers Markdown et MDX. + +### Composants d'interface utilisateur + +Les composants construits avec des frameworks d'interface utilisateur tels que React ou Vue peuvent facilement ajouter de grandes quantités de JavaScript à une page. +Starlight étant construit sur Astro, les composants de ce type chargent **zéro JavaScript côté client par défaut** grâce à [Astro Islands][islands]. + +### Mise en cache + +La mise en cache est utilisée pour contrôler la durée pendant laquelle un navigateur stocke et réutilise les données qu'il a déjà téléchargées. +Une bonne stratégie de mise en cache permet à l'utilisateur d'obtenir un nouveau contenu dès qu'il est modifié, tout en évitant de télécharger inutilement le même contenu à plusieurs reprises lorsqu'il n'a pas changé. + +La façon la plus courante de configurer la mise en cache est d'utiliser l'en-tête HTTP [`Cache-Control`][cache]. +Lorsque vous utilisez Starlight, vous pouvez définir une longue durée de mise en cache pour tout ce qui se trouve dans le répertoire `/_astro/`. +Ce répertoire contient des fichiers CSS, JavaScript, et d'autres actifs intégrés qui peuvent être mis en cache pour toujours, réduisant ainsi les téléchargements inutiles : + +``` +Cache-Control: public, max-age=604800, immutable +``` + +La configuration de la mise en cache dépend de votre hébergeur. Par exemple, Vercel applique cette stratégie de mise en cache pour vous sans configuration nécessaire, tandis que vous pouvez définir des [en-têtes personnalisés pour Netlify][ntl-headers] en ajoutant un fichier `public/_headers` à votre projet : + +``` +/_astro/* + Cache-Control: public + Cache-Control: max-age=604800 + Cache-Control: immutable +``` + +[cache]: https://csswizardry.com/2019/03/cache-control-for-civilians/ +[ntl-headers]: https://docs.netlify.com/routing/headers/ + +## Consommation d'énergie + +La façon dont une page web est construite peut avoir un impact sur la puissance nécessaire pour fonctionner sur l'appareil d'un utilisateur. +En utilisant un minimum de JavaScript, Starlight réduit la puissance de traitement dont le téléphone, la tablette ou l'ordinateur d'un utilisateur a besoin pour charger et afficher les pages. + +Soyez vigilant lorsque vous ajoutez des fonctionnalités telles que des scripts de suivi analytique ou des contenus à forte teneur en JavaScript, comme des vidéos intégrées, car ils peuvent augmenter la consommation d'énergie de la page. +Si vous avez besoin d'analyses, envisagez de choisir une option légère comme [Cabin][cabin], [Fathom][fathom], ou [Plausible][plausible]. +Les vidéos intégrées comme celles de YouTube et de Vimeo peuvent être améliorées en attendant de [charger la vidéo lors de l'interaction avec l'utilisateur][lazy-video]. +Des paquets comme [`astro-embed`][embed] peuvent aider pour les services communs. + +:::tip[Le saviez-vous ?] +L'analyse et la compilation de JavaScript est l'une des tâches les plus coûteuses pour les navigateurs. +Par rapport au rendu d'une image JPEG de même taille, [le traitement de JavaScript peut prendre plus de 30 fois plus de temps][coût-de-js]. +::: + +[cabin]: https://withcabin.com/ +[fathom]: https://usefathom.com/ +[plausible]: https://plausible.io/ +[lazy-video]: https://web.dev/iframe-lazy-loading/ +[embed]: https://www.npmjs.com/package/astro-embed +[cost-of-js]: https://medium.com/dev-channel/the-cost-of-javascript-84009f51e99e + +## Hébergement + +Le lieu d'hébergement d'une page web peut avoir un impact important sur le degré de respect de l'environnement de votre site de documentation. +Les centres de données et les fermes de serveurs peuvent avoir un impact écologique important, notamment en raison de leur consommation élevée d'électricité et de leur utilisation intensive de l'eau. + +Le choix d'un hébergeur utilisant des énergies renouvelables se traduira par une réduction des émissions de carbone pour votre site. Le [Green Web Directory][gwb] est un outil qui peut vous aider à trouver des hébergeurs. + +[gwb]: https://www.thegreenwebfoundation.org/directory/ + +## Comparaisons + +Curieux de savoir comment les autres frameworks de documentation se comparent ? +Ces tests avec le [Website Carbon Calculator][wcc] comparent des pages similaires construites avec différents outils. + +| Framework | CO₂ par page visitée | +| --------------------------- | ------------------ | +| [Starlight][sl-carbon] | 0.01g | +| [VitePress][vp-carbon] | 0.05g | +| [Sphinx][sx-carbon] | 0.07g | +| [MkDocs][mk-carbon] | 0.10g | +| [Nextra][nx-carbon] | 0.11g | +| [Docusaurus][ds-carbon] | 0.24g | +| [Read the Docs][rtd-carbon] | 0.24g | +| [GitBook][gb-carbon] | 0.71g | + +<small>Données collectées le 14 mai 2023. Cliquez sur un lien pour voir les chiffres actualisés.</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/ +[sx-carbon]: https://www.websitecarbon.com/website/sphinx-doc-org-en-master-usage-quickstart-html/ +[mk-carbon]: https://www.websitecarbon.com/website/mkdocs-org-getting-started/ +[nx-carbon]: https://www.websitecarbon.com/website/nextra-site-docs-docs-theme-start/ +[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/ + +## Plus de ressources + +### Outils + +- [Website Carbon Calculator][wcc] +- [Ecograder](https://ecograder.com/) +- [WebPageTest Carbon Control](https://www.webpagetest.org/carbon-control/) +- [Ecoping](https://ecoping.earth/) + +### Articles et discussions + +- [“Building a greener web”](https://youtu.be/EfPoOt7T5lg), conférence de Michelle Barker +- [“Sustainable Web Development Strategies Within An Organization”](https://www.smashingmagazine.com/2022/10/sustainable-web-development-strategies-organization/), article par Michelle Barker +- [“A sustainable web for everyone”](https://2021.stateofthebrowser.com/speakers/tom-greenwood/), conférence de Tom Greenwood +- [“How Web Content Can Affect Power Usage”](https://webkit.org/blog/8970/how-web-content-can-affect-power-usage/), article de Benjamin Poulain et Simon Fraser + +[sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/ +[bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think +[http]: https://httparchive.org/reports/state-of-the-web +[assets]: https://docs.astro.build/en/guides/assets/ +[islands]: https://docs.astro.build/en/concepts/islands/ +[wcc]: https://www.websitecarbon.com/ diff --git a/docs/src/content/docs/fr-FR/getting-started.mdx b/docs/src/content/docs/fr-FR/getting-started.mdx new file mode 100644 index 00000000..b40b1c39 --- /dev/null +++ b/docs/src/content/docs/fr-FR/getting-started.mdx @@ -0,0 +1,86 @@ +--- +title: Mise en route +description: Apprenez à créer votre prochain site de documentation avec Starlight by Astro. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +:::caution[Work in progress] +Starlight est en début de développement. +Si vous trouvez quelque chose qui ne fonctionne pas, [ouvrez une issue sur GitHub](https://github.com/withastro/starlight/issues/new/choose) ou faites-le nous savoir sur [Discord](https://astro.build/chat). +::: + +## Créer un nouveau projet + +Starlight est un thème de documentation complet construit sur le framework [Astro](https://astro.build). + +Vous pouvez créer un nouveau projet Astro + Starlight en utilisant la commande suivante : + +<Tabs> +<TabItem label="npm"> + +```sh +# créer un nouveau projet avec npm +npm create astro@latest -- --template starlight +``` + +</TabItem> +<TabItem label="pnpm"> + +```sh +# créer un nouveau projet avec pnpm +pnpm create astro --template starlight +``` + +</TabItem> +<TabItem label="Yarn"> + +```sh +# créer un nouveau projet avec yarn +yarn create astro --template starlight +``` + +</TabItem> +</Tabs> + +Cela créera un nouveau [répertoire de projet](/fr-FR/guides/projet-structure/) avec tous les fichiers et configurations nécessaires pour votre site. + +:::tip[Voir en action] +Essayez Starlight dans votre navigateur : +[ouvrir le modèle sur StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics). +::: + +## Créer du contenu avec Starlight + +Starlight est prêt pour que vous puissiez ajouter du nouveau contenu, ou apporter vos fichiers existants ! + +### Formats de fichiers + +Starlight prend en charge la création de contenu en Markdown et MDX. (Vous pouvez ajouter la prise en charge de Markdoc en installant l'intégration expérimentale [Astro Markdoc integration](https://docs.astro.build/fr/guides/integrations-guide/markdoc/).) + +### Ajouter des pages +Ajoutez automatiquement de nouvelles pages à votre site en créant des fichiers `.md` ou `.mdx` dans `src/content/docs/`. Ajoutez des sous-dossiers pour organiser vos fichiers, et pour créer plusieurs segments de chemin : + +```js +`src/content/docs/hello-world.md` -> `votre-site/hello-world` +`src/content/docs/guides/faq.md` -> `votre-site/guides/faq` +``` + +### Type-safe frontmatter + +Toutes les pages Starlight partagent un [ensemble commun de propriétés de présentation](/fr-FR/reference/frontmatter/) personnalisable pour contrôler l'apparence de la page : + +```md +--- +title: Bonjour, le monde ! +description: Ceci est une page de mon site web propulsé par Starlight. +--- +``` + +Si vous oubliez quelque chose d'important, Starlight vous le fera savoir. + +## Déployer votre site web Starlight + +Une fois que vous avez créé et personnalisé votre site Web Starlight, vous pouvez le déployer sur un serveur Web ou une plateforme d'hébergement de votre choix, y compris Netlify, Vercel, GitHub Pages et bien d'autres. + +[Pour en savoir plus sur le déploiement d'un site Astro, consultez la documentation Astro](https://docs.astro.build/fr/guides/deploy/) diff --git a/docs/src/content/docs/fr-FR/guides/authoring-content.md b/docs/src/content/docs/fr-FR/guides/authoring-content.md new file mode 100644 index 00000000..1e6da7b2 --- /dev/null +++ b/docs/src/content/docs/fr-FR/guides/authoring-content.md @@ -0,0 +1,209 @@ +--- +title: Création de contenu en Markdown +description: Un aperçu de la syntaxe Markdown prise en charge par Starlight. +--- + +Starlight prend en charge l'ensemble de la syntaxe [Markdown](https://daringfireball.net/projects/markdown/) dans les fichiers `.md` ainsi que la syntaxe frontale [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) pour définir des métadonnées telles qu'un titre et une description. + +Veillez à consulter les [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) ou les [Markdoc docs](https://markdoc.dev/docs/syntax) si vous utilisez ces formats de fichiers, car la prise en charge et l'utilisation de Markdown peuvent varier. + +## Styles en ligne + +Le texte peut être **gras**, _italique_, ou ~~barré~~. + +```md +Le texte peut être **gras**, _italique_, ou ~~barré~~. +``` + +Vous pouvez [faire un lien vers une autre page](/fr-FR/getting-started/). + +```md +Vous pouvez [faire un lien vers une autre page](/fr-FR/getting-started/). +``` + +Vous pouvez mettre en évidence le `code en ligne` à l'aide d'un astérisque. + +```md +Vous pouvez mettre en évidence le `code en ligne` à l'aide de barres de défilement. +``` + +## Images + +Les images dans Starlight utilisent la prise en charge intégrée des ressources optimisées d'Astro. + +Markdown et MDX supportent la syntaxe Markdown pour l'affichage des images qui inclut le texte alt pour les lecteurs d'écran et les technologies d'assistance. + +![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) + +```md +![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) +``` + +Les chemins d'accès relatifs aux images sont également supportés pour les images stockées localement dans votre projet. + +```md +// src/content/docs/page-1.md + +![Une fusée dans l'espace.](../../assets/images/rocket.svg) +``` + +## En-têtes + +Vous pouvez structurer le contenu à l'aide d'un titre. En Markdown, les titres sont indiqués par un nombre de `#` en début de ligne. + +### Comment structurer le contenu d'une page dans Starlight + +Starlight est configuré pour utiliser automatiquement le titre de votre page comme titre de premier niveau et inclura un titre "Aperçu" en haut de la table des matières de chaque page. Nous vous recommandons de commencer chaque page par un paragraphe de texte normal et d'utiliser des titres de page à partir de `<h2>` : + +```md +--- +title: Guide Markdown +description: Comment utiliser Markdown dans Starlight +--- + +Cette page décrit comment utiliser Markdown dans Starlight. + +## Styles en ligne + +## Titres + +``` + +### Liens d'ancrage automatiques pour les titres + +L'utilisation de titres en Markdown vous donnera automatiquement des liens d'ancrage afin que vous puissiez accéder directement à certaines sections de votre page : + +```md +--- +title: Ma page de contenu +description: Comment utiliser les liens d'ancrage intégrés de Starlight +--- +## Introduction + +Je peux faire un lien vers [ma conclusion](#conclusion) plus bas sur la même page. + +## Conclusion + +`https://my-site.com/page1/#introduction` renvoie directement à mon Introduction. +``` + +Les titres de niveau 2 (`<h2>`) et de niveau 3 (`<h3>`) apparaissent automatiquement dans la table des matières de la page. + +## Asides + +Les Asides (également connus sous le nom de "callouts") sont utiles pour afficher des informations secondaires à côté du contenu principal d'une page. + +Starlight fournit une syntaxe Markdown personnalisée pour le rendu des apartés. Les blocs d'apartés sont indiqués en utilisant une paire de triples points `:::` pour envelopper votre contenu, et peuvent être de type `note`, `tip`, `caution` ou `danger`. + +Vous pouvez imbriquer n'importe quel autre type de contenu Markdown à l'intérieur d'un aparté, mais les aparté sont mieux adaptés à des morceaux de contenu courts et concis. + +### Note aside + +:::note +Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : + +```sh +npm run create astro@latest --template starlight +``` + +::: + +````md +:::note +Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : + +```sh +npm run create astro@latest --template starlight +``` + +::: +```` + +### Titres personnalisés dans les asides + +Vous pouvez spécifier un titre personnalisé pour l'aparté entre crochets après le type d'aparté, par exemple `:::tip[Le saviez-vous ?]`. + +:::tip[Le saviez-vous ?] +Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). +::: + +```md +:::tip[Le saviez-vous ?] +Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). +::: +``` + +### Plus de types pour l'aside + +Les apartés de type Attention et Danger sont utiles pour attirer l'attention de l'utilisateur sur des détails qui pourraient le faire trébucher. +Si vous les utilisez souvent, c'est peut-être aussi le signe que la chose que vous documentez gagnerait à être repensée. + +:::caution +Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). +::: + +:::danger +Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. + +- Navigation claire +- Thème de couleurs configurable par l'utilisateur +- [Support i18n](/fr-FR/guides/i18n) + +::: + +```md +:::caution +Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). +::: + +:::danger +Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. + +- Navigation claire +- Thème de couleurs configurable par l'utilisateur +- [Support i18n](/fr-FR/guides/i18n) + +::: +``` + +## Blockquotes + +> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. +> +> Les guillemets sont indiqués par un `>` au début de chaque ligne. + +```md +> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. +> +> Les guillemets sont indiqués par un `>` au début de chaque ligne. +``` + +## Code blocks + +Un bloc de code est indiqué par un bloc avec trois crochets <code>```</code> au début et à la fin. Vous pouvez indiquer le langage de programmation utilisé après les premiers crochets. + +```js +// Code Javascript avec mise en évidence de la syntaxe. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` + +````md +```js +// Code Javascript avec mise en évidence de la syntaxe. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` +```` + +```md +Les longs blocs de code d'une seule ligne ne doivent pas être enveloppés. Ils doivent défiler horizontalement s'ils sont trop longs. Cette ligne devrait être suffisamment longue pour le démontrer. +``` + +## Autres fonctionnalités courantes de Markdown + +Starlight prend en charge toutes les autres syntaxes de rédaction Markdown, telles que les listes et les tableaux. Voir [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) pour un aperçu rapide de tous les éléments de la syntaxe Markdown. diff --git a/docs/src/content/docs/fr-FR/guides/components.mdx b/docs/src/content/docs/fr-FR/guides/components.mdx new file mode 100644 index 00000000..5e1000cf --- /dev/null +++ b/docs/src/content/docs/fr-FR/guides/components.mdx @@ -0,0 +1,111 @@ +--- +title: Composants +description: Utilisation de composants dans MDX avec Starlight. +--- + +Les composants vous permettent de réutiliser facilement un élément d'interface utilisateur ou de style de manière cohérente. +Il peut s'agir par exemple d'une carte de lien ou d'une intégration YouTube. +Starlight prend en charge l'utilisation de composants dans les fichiers [MDX](https://mdxjs.com/) et fournit des composants courants que vous pouvez utiliser. + +[Pour en savoir plus sur la création de composants, consultez les Astro Docs](https://docs.astro.build/fr/core-concepts/astro-components/). + +## Utilisation d'un composant + +Vous pouvez utiliser un composant en l'important dans votre fichier MDX et en le rendant sous forme de balise JSX. +Ces balises ressemblent à des balises HTML mais commencent par une lettre majuscule correspondant au nom de votre déclaration `import` : + +```mdx +--- +# src/content/docs/index.mdx +title: Bienvenue dans ma documentation +--- + +import SomeComponent from '../../components/SomeComponent.astro'; +import AnotherComponent from '../../components/AnotherComponent.astro'; + +<SomeComponent prop="something" /> + +<AnotherComponent> + Les composants peuvent également contenir du **contenu imbriqué**. +</AnotherComponent> +``` + +Starlight étant alimenté par Astro, vous pouvez ajouter la prise en charge des composants construits avec n'importe quel [cadre d'interface utilisateur pris en charge (React, Preact, Svelte, Vue, Solid, Lit et Alpine)](https://docs.astro.build/fr/core-concepts/framework-components/) dans vos fichiers MDX. +Pour en savoir plus sur [l'utilisation de composants dans MDX](https://docs.astro.build/fr/guides/markdown-content/#using-components-in-mdx), consultez la documentation Astro. + +## Composants intégrés + +Starlight fournit quelques composants intégrés pour les cas d'utilisation courants de la documentation. +Ces composants sont disponibles dans le paquet `@astrojs/starlight/components`. + +### Onglets + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Vous pouvez afficher une interface à onglets en utilisant les composants `<Tabs>` et `<TabItem>`. +Chaque `<TabItem>` doit avoir un `label` à afficher aux utilisateurs. + +```mdx +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +<Tabs> + <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> + <TabItem label="Moons">Io, Europa, Ganymede</TabItem> +</Tabs> +``` + +Le code ci-dessus génère les onglets suivants sur la page : + +<Tabs> + <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> + <TabItem label="Moons">Io, Europa, Ganymede</TabItem> +</Tabs> + +### Cards + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +Vous pouvez afficher du contenu dans une boîte correspondant aux styles de Starlight en utilisant le composant `<Card>`. +Enveloppez plusieurs cartes dans le composant `<CardGrid>` pour afficher les cartes côte à côte lorsqu'il y a suffisamment d'espace. + +Une `<Card>` nécessite un `titre` et peut éventuellement inclure un attribut `icon` fixé au nom de [l'une des icônes intégrées de Starlight](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts). + +```mdx +import { Card, CardGrid } from '@astrojs/starlight/components'; + +<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> + +<CardGrid> + <Card title="Stars" icon="star"> + Sirius, Vega, Betelgeuse + </Card> + <Card title="Moons" icon="moon"> + Io, Europa, Ganymede + </Card> +</CardGrid> +``` + +Le code ci-dessus génère ce qui suit sur la page : + +<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> + +<CardGrid> + <Card title="Stars" icon="star"> + Sirius, Vega, Betelgeuse + </Card> + <Card title="Moons" icon="moon"> + Io, Europa, Ganymede + </Card> +</CardGrid> + +:::tip +Utilisez une grille de cartes sur votre page d'accueil pour afficher les principales caractéristiques de votre projet. +Ajoutez l'attribut `stagger` pour décaler verticalement la deuxième colonne de cartes et ajouter un intérêt visuel : + +```astro +<CardGrid stagger> + <!-- cards --> +</CardGrid> +``` + +::: diff --git a/docs/src/content/docs/fr-FR/guides/i18n.mdx b/docs/src/content/docs/fr-FR/guides/i18n.mdx new file mode 100644 index 00000000..0bde4184 --- /dev/null +++ b/docs/src/content/docs/fr-FR/guides/i18n.mdx @@ -0,0 +1,201 @@ +--- +title: Internationalisation (i18n) +description: Apprenez à configurer votre site Starlight pour qu'il prenne en charge plusieurs langues. +--- + +import FileTree from '../../../components/file-tree.astro'; + +Starlight offre une prise en charge intégrée des sites multilingues, y compris le routage, le contenu de repli et la prise en charge complète des langues de droite à gauche (RTL). + +## Configurer i18n + +1. Indiquez à Starlight les langues que vous prenez en charge en passant `locales` et `defaultLocale` à l'intégration Starlight : + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + // Définit l'anglais comme langue par défaut pour ce site. + defaultLocale: 'en', + locales: { + // Docs en anglais dans `src/content/docs/en/` + en: { + label: 'English', + }, + // Documentation en chinois simplifié dans `src/content/docs/zh/` + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + // docs en arabe dans `src/content/docs/ar/` + ar: { + label: 'العربية', + dir: 'rtl', + }, + }, + }), + ], + }); + ``` + + Votre `defaultLocale` sera utilisé pour le contenu de repli et les étiquettes de l'interface utilisateur, donc choisissez la langue dans laquelle vous êtes le plus susceptible de commencer à écrire du contenu, ou pour laquelle vous avez déjà du contenu. + +2. Créez un répertoire pour chaque langue dans `src/content/docs/`. + Par exemple, pour la configuration montrée ci-dessus, créez les dossiers suivants : + + <FileTree> + + - src/ + - content/ + - docs/ + - ar/ + - en/ + - zh/ + + </FileTree> + +3. Vous pouvez maintenant ajouter des fichiers de contenu dans vos répertoires de langues. Utilisez le même nom de fichier pour associer les pages d'une langue à l'autre et profiter de l'ensemble des fonctionnalités i18n de Starlight, y compris le contenu de repli, les avis de traduction, etc. + + Par exemple, créez `ar/index.md` et `en/index.md` pour représenter la page d'accueil en arabe et en anglais respectivement. + +### Utiliser une racine locale + +Vous pouvez utiliser une racine locale pour servir une langue sans aucun préfixe i18n dans son chemin. Par exemple, si l'anglais est votre racine locale, le chemin d'une page en anglais ressemblera à `/about` au lieu de `/en/about`. + +Pour définir une racine locale, utilisez la clé `root` dans votre configuration `locales`. Si la racine locale est aussi la locale par défaut de votre contenu, supprimez `defaultLocale` ou donnez-lui la valeur `'root''. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + defaultLocale: 'root', // optionnel + locales: { + root: { + label: 'English', + lang: 'en', // lang est nécessaire pour les locales de la racine + }, + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Lorsque vous utilisez une locale `root`, gardez les pages pour cette langue directement dans `src/content/docs/` au lieu d'un dossier dédié à la langue. Par exemple, voici les fichiers de la page d'accueil pour l'anglais et le chinois en utilisant la configuration ci-dessus : + +<FileTree> + +- src/ + - content/ + - docs/ + - **index.md** + - zh/ + - **index.md** + +</FileTree> + +#### Sites monolingues + +Par défaut, Starlight est un site monolingue (anglais). Pour créer un site monolingue dans une autre langue, définissez-la comme `root` dans votre configuration `locales` : + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Cela vous permet de remplacer la langue par défaut de Starlight sans activer d'autres fonctions d'internationalisation pour les sites multilingues, telles que le sélecteur de langue. + +## Contenu de remplacement + +Starlight s'attend à ce que vous créiez des pages équivalentes dans toutes vos langues. Par exemple, si vous avez un fichier `en/about.md`, créez un `about.md` pour chaque autre langue que vous supportez. Cela permet à Starlight de fournir un contenu de remplacement automatique pour les pages qui n'ont pas encore été traduites. + +Si une traduction n'est pas encore disponible pour une langue, Starlight affichera aux lecteurs le contenu de cette page dans la langue par défaut (définie via `defaultLocale`). Par exemple, si vous n'avez pas encore créé de version française de votre page À propos et que votre langue par défaut est l'anglais, les visiteurs de `/fr/about` verront le contenu anglais de `/en/about` avec un avis indiquant que cette page n'a pas encore été traduite. Cela vous permet d'ajouter du contenu dans votre langue par défaut et de le traduire progressivement lorsque vos traducteurs en ont le temps. + +## Traduire l'interface utilisateur de Starlight + +En plus d'héberger des fichiers de contenu traduits, Starlight vous permet de traduire les chaînes de l'interface utilisateur par défaut (par exemple, l'en-tête "Sur cette page" dans la table des matières) afin que vos lecteurs puissent découvrir votre site entièrement dans la langue sélectionnée. + +Les chaînes d'interface utilisateur traduites en anglais, allemand, japonais, portugais et espagnol sont fournies d'office, et nous acceptons les [contributions pour ajouter d'autres langues par défaut](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). + +Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collecte de données `i18n`. + +1. Configurez la collection de données `i18n` dans `src/content/config.ts` si elle n'est pas déjà configurée : + + ```js + // src/content/config.ts + import { defineCollection } from 'astro:content'; + import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; + + export const collections = { + docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), + }; + ``` + +2. Créez un fichier JSON dans `src/content/i18n/` pour chaque locale supplémentaire pour laquelle vous voulez fournir des chaînes de traduction pour l'interface utilisateur. + Par exemple, cela ajouterait des fichiers de traduction pour l'arabe et le chinois simplifié : + + <FileTree> + + - src/ + - content/ + - i18n/ + - ar.json + - zh-CN.json + + </FileTree> + +3. Ajoutez des traductions pour les clés que vous souhaitez traduire dans les fichiers JSON. Traduire uniquement les valeurs, en laissant les clés en anglais (e.g. `"search.label": "Buscar"`). + + Il s'agit des valeurs anglaises par défaut des chaînes de caractères existantes avec lesquelles Starlight est livré : + + ```json + { + "skipLink.label": "Aller au contenu", + "search.label": "rechercher", + "search.shortcutLabel": "(Presser / pour rechercher)", + "search.cancelLabel": "Annuler", + "themeSelect.accessibleLabel": "Selectionner le thème", + "themeSelect.dark": "Dark", + "themeSelect.light": "Light", + "themeSelect.auto": "Auto", + "languageSelect.accessibleLabel": "Selectionner la langue", + "menuButton.accessibleLabel": "Menu", + "sidebarNav.accessibleLabel": "Main", + "tableOfContents.onThisPage": "Sur cette page", + "tableOfContents.overview": "Vue d'ensemble", + "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", + "page.editLink": "Editer la page", + "page.lastUpdated": "Dernière mise à jour :", + "page.previousLink": "Suivant", + "page.nextLink": "Précédent" + } + ``` diff --git a/docs/src/content/docs/fr-FR/guides/project-structure.mdx b/docs/src/content/docs/fr-FR/guides/project-structure.mdx new file mode 100644 index 00000000..4d301614 --- /dev/null +++ b/docs/src/content/docs/fr-FR/guides/project-structure.mdx @@ -0,0 +1,48 @@ +--- +title: Structure du projet +description: Apprenez à organiser les fichiers dans votre projet Starlight. +--- + +Ce guide vous montrera comment un projet Starlight est organisé et ce que font les différents fichiers de votre projet. + +Les projets Starlight suivent généralement la même structure de fichiers et de répertoires que les autres projets Astro. Voir [la documentation sur la structure des projets Astro](https://docs.astro.build/fr/core-concepts/project-structure/) pour plus de détails. + +## Fichiers et répertoires + +- `astro.config.mjs` — Le fichier de configuration d'Astro ; inclut l'intégration et la configuration de Starlight. +- `src/content/config.ts` — Fichier de configuration des collections de contenu ; ajoute les schémas de la matière première de Starlight à votre projet. +- `src/content/docs/` — Fichiers de contenu. Starlight transforme chaque fichier `.md`, `.mdx` ou `.mdoc` de ce répertoire en une page de votre site. +- `src/content/i18n/` (optionnel) — Données de traduction pour prendre en charge l'[internationalisation](/fr-FR/guides/i18n/). +- `src/` — Autre code source et fichiers (composants, styles, images, etc.) pour votre projet. +- `public/` — Actifs statiques (polices, favicon, PDFs, etc.) qui ne seront pas traités par Astro. + +## Exemple de contenu de projet + +Un répertoire de projet Starlight peut ressembler à ceci : + +import FileTree from '../../../components/file-tree.astro'; + +<FileTree> + +- public/ + - favicon.svg +- src/ + - assets/ + - logo.svg + - screenshot.jpg + - components/ + - CustomButton.astro + - InteractiveWidget.jsx + - content/ + - docs/ + - guides/ + - 01-getting-started.md + - 02-advanced.md + - index.mdx + - config.ts + - env.d.ts +- astro.config.mjs +- package.json +- tsconfig.json + +</FileTree> diff --git a/docs/src/content/docs/fr-FR/index.mdx b/docs/src/content/docs/fr-FR/index.mdx new file mode 100644 index 00000000..14966082 --- /dev/null +++ b/docs/src/content/docs/fr-FR/index.mdx @@ -0,0 +1,44 @@ +--- +title: Starlight 🌟 Construire des sites de documentation avec Astro +description: Starlight vous aide à créer de magnifiques sites web de documentation très performants avec Astro. +template: splash +hero: + title: Faites briller vos documents avec Starlight + tagline: Tout ce dont vous avez besoin pour créer un excellent site web de documentation. Rapide, accessible et facile à utiliser. + image: + file: ../../../assets/hero-star.webp + actions: + - text: Mise en route + icon: right-arrow + variant: primary + link: /fr-FR/getting-started/ + - text: Voir sur GitHub + icon: external + link: https://github.com/withastro/starlight +--- + +import { CardGrid, Card } from '@astrojs/starlight/components'; +import AboutAstro from '../../components/about-astro.astro'; + +<CardGrid stagger> + <Card title="Une documentation qui enchante" icon="open-book"> + Comprend : Navigation dans le site, recherche, internationalisation, référencement naturel, typographie facile à lire, mise en évidence du code, mode sombre, etc. + </Card> + <Card title="Propulsé par Astro" icon="rocket"> + Exploitez toute la puissance et les performances d'Astro. Étendez Starlight avec vos intégrations et bibliothèques Astro préférées. + </Card> + <Card title="Markdown, Markdoc, et MDX" icon="document"> + Apportez votre langage de balisage préféré. Starlight vous offre une validation frontmatter intégrée avec la sécurité de type TypeScript. + </Card> + <Card title="Apportez vos propres composants d'interface utilisateur" icon="puzzle"> + Starlight est une solution de documentation complète, indépendante du cadre de travail. Étendez avec React, Vue, Svelte, Solid, et plus encore. + </Card> +</CardGrid> + +<AboutAstro title="Présenté par"> +Astro est le framework web tout-en-un conçu pour la vitesse. +Tirez votre contenu de n'importe où et déployez-le partout, le tout alimenté par vos composants et bibliothèques d'interface utilisateur préférés. + +[En savoir plus sur Astro](https://astro.build/) + +</AboutAstro> diff --git a/docs/src/content/docs/fr-FR/reference/configuration.md b/docs/src/content/docs/fr-FR/reference/configuration.md new file mode 100644 index 00000000..4e6ab2f9 --- /dev/null +++ b/docs/src/content/docs/fr-FR/reference/configuration.md @@ -0,0 +1,326 @@ +--- +title: Référence de configuration +description: Une vue d'ensemble de toutes les options de configuration prises en charge par Starlight. +--- + +## Configuration de l'intégration `starlight` + +Starlight est une intégration construite sur le framework web [Astro](https://astro.build). Vous pouvez configurer votre projet dans le fichier de configuration Astro `astro.config.mjs` : + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: "Mon délicieux site de docs", + }), + ], +}); +``` + +Vous pouvez passer les options suivantes à l'intégration `starlight`. + +### `title` (obligatoire) + +**type:** `string` + +Définissez le titre de votre site web. Il sera utilisé dans les métadonnées et dans le titre de l'onglet du navigateur. + +### `description` + +**type:** `string` + +Définissez la description de votre site web. Utilisée dans les métadonnées partagées avec les moteurs de recherche dans la balise `<meta name="description">` si `description` n'est pas définie dans le frontmatter d'une page. + +### `logo` + +**type:** [`LogoConfig`](#logoconfig) + +Définit une image de logo à afficher dans la barre de navigation à côté ou à la place du titre du site. Vous pouvez soit définir une seule propriété `src`, soit définir des sources d'images séparées pour `light` et `dark`. + +```js +starlight({ + logo: { + src: '/src/assets/my-logo.svg', + }, +}); +``` + +#### `LogoConfig` + +```ts +type LogoConfig = { alt?: string; replacesTitle?: boolean } & ( + | { src: string } + | { light: string; dark: string } +); +``` + +### `tableOfContents` + +**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` +**default:** `{ minHeadingLevel: 2; maxHeadingLevel: 3; }` + +Configurez la table des matières affichée à droite de chaque page. Par défaut, les titres `<h2>` et `<h3>` seront inclus dans cette table des matières. + +### `editLink` + +**type:** `{ baseUrl: string }` + +Permet d'activer les liens "Modifier cette page" en définissant l'URL de base qu'ils doivent utiliser. Le lien final sera `editLink.baseUrl` + le chemin de la page actuelle. Par exemple, pour permettre l'édition de pages dans le repo `withastro/starlight` sur GitHub : + +```js +starlight({ + editLink: { + baseUrl: 'https://github.com/withastro/starlight/edit/main/', + }, +}); +``` + +Avec cette configuration, une page `/introduction` aurait un lien d'édition pointant vers `https://github.com/withastro/starlight/edit/main/src/docs/introduction.md`. + +### `sidebar` + +**type:** [`SidebarGroup[]`](#sidebargroup) + +Configure les éléments de navigation de la barre latérale de votre site. + +Une barre latérale est un tableau de groupes, chacun avec un `label` pour le groupe et un tableau `items` ou un objet de configuration `autogenerate`. + +Vous pouvez définir manuellement le contenu d'un groupe en utilisant `items`, qui est un tableau pouvant inclure des liens et des sous-groupes. Vous pouvez aussi générer automatiquement le contenu d'un groupe à partir d'un répertoire spécifique de votre documentation, en utilisant `autogenerate`. + +```js +starlight({ + sidebar: [ + // Un groupe intitulé "Commencer ici" contenant deux liens. + { + label: 'Commencer ici', + items: [ + { label: 'Introduction', link: '/intro' }, + { label: 'Etapes', link: '/next-steps' }, + ], + }, + // Un groupe qui renvoie à toutes les pages du répertoire de référence. + { + label: 'Référence', + autogenerate: { directory: 'reference' }, + }, + ], +}); +``` + +#### Tri + +Les groupes de barres latérales générées automatiquement sont triés par nom de fichier et par ordre alphabétique. +Par exemple, une page générée à partir de `astro.md` apparaîtrait au-dessus de la page de `starlight.md`. + +#### Traduire les étiquettes + +Si votre site est multilingue, le `label` de chaque élément est considéré comme étant dans la locale par défaut. Vous pouvez définir une propriété `translations` pour fournir des étiquettes pour les autres langues supportées : + +```js +sidebar: [ + // Un exemple de barre latérale avec des étiquettes traduites en anglais. + { + label: 'Commencer ici', + translations: { en: 'Start here' }, + items: [ + { + label: 'Bien démarrer', + translations: { en: 'Getting Started' }, + link: '/getting-started', + }, + { + label: 'Structure du projet', + translations: { en: 'Project Structure' }, + link: '/structure', + }, + ], + }, +]; +``` + +#### `SidebarGroup` + +```ts +type SidebarGroup = + | { + label: string; + translations?: Record<string, string>; + items: Array<LinkItem | SidebarGroup>; + } + | { + label: string; + translations?: Record<string, string>; + autogenerate: { + directory: string; + }; + }; +``` + +#### `LinkItem` + +```ts +interface LinkItem { + label: string; + link: string; +} +``` + +### `locales` + +**type:** `{ [dir: string]: LocaleConfig }` + +Configurez l'internationalisation (i18n) de votre site en définissant les `locales` supportées. + +Chaque entrée doit utiliser comme clé le répertoire dans lequel les fichiers de cette langue sont sauvegardés. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Site', + // Définit l'anglais comme langue par défaut pour ce site. + defaultLocale: 'en', + locales: { + // Documentations en anglais danse trouve dans `src/content/docs/en/` + en: { + label: 'English', + }, + // Documentations en Chinois simplifié se trouve dans `src/content/docs/zh/` + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + // Documentations en Arabe se trouve dans `src/content/docs/ar/` + ar: { + label: 'العربية', + dir: 'rtl', + }, + }, + }), + ], +}); +``` + +#### Options des paramètres linguistiques + +Vous pouvez définir les options suivantes pour chaque locale : + +##### `label` (obligatoire) + +**type:** `string` + +L'étiquette de cette langue à afficher aux utilisateurs, par exemple dans le sélecteur de langue. Le plus souvent, il s'agit du nom de la langue tel qu'un utilisateur de cette langue s'attendrait à le lire, par exemple `"English"`, `"العربية"`, ou `"简体中文"`. + +##### `lang` + +**type:** `string` + +La balise BCP-47 pour cette langue, par exemple `"en"`, `"ar"`, ou `"zh-CN"`. S'il n'est pas défini, le nom du répertoire de la langue sera utilisé par défaut. + +##### `dir` + +**type:** `'ltr' | 'rtl'` + +Le sens d'écriture de cette langue ; `"ltr"` pour gauche à droite (par défaut) ou `"rtl"` pour droite à gauche. + +#### Locale racine + +Vous pouvez servir la langue par défaut sans répertoire `/lang/` en définissant une locale `root` : + +```js +starlight({ + locales: { + root: { + label: 'English', + lang: 'en', + }, + fr: { + label: 'Français', + }, + }, +}); +``` + +Par exemple, cela vous permet de servir `/getting-started/` comme une route anglaise et d'utiliser `/fr/getting-started/` comme la page française équivalente. + +### `defaultLocale` + +**type:** `string` + +Définit la langue par défaut pour ce site. +La valeur doit correspondre à l'une des clés de votre objet [`locales`](#locales). +(Si votre langue par défaut est votre [root locale](#root-locale), vous pouvez sauter cette étape). + +La locale par défaut sera utilisée pour fournir un contenu de remplacement lorsque les traductions sont manquantes. + +### `social` + +**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }` + +Détails optionnels sur les comptes de médias sociaux pour ce site. L'ajout de l'un d'entre eux les affichera sous forme de liens iconiques dans l'en-tête du site. + +```js +starlight({ + social: { + discord: 'https://astro.build/chat', + github: 'https://github.com/withastro/starlight', + mastodon: 'https://m.webtoo.ls/@astro', + twitter: 'https://twitter.com/astrodotbuild', + }, +}); +``` + +### `customCss` + +**type:** `string[]` + +Fournit des fichiers CSS pour personnaliser l'aspect et la convivialité de votre site Starlight. + +Prend en charge les fichiers CSS locaux relatifs à la racine de votre projet, par exemple `'/src/custom.css'`, et les CSS que vous avez installés en tant que module npm, par exemple `'@fontsource/roboto'`. + +```js +starlight({ + customCss: ['/src/custom-styles.css', '@fontsource/roboto'], +}); +``` + +### `head` + +**type:** [`HeadConfig[]`](#headconfig) + +Ajoute des balises personnalisées au `<head>` de votre site Starlight. +Cela peut être utile pour ajouter des analyses et d'autres scripts et ressources tiers. + +```js +starlight({ + head: [ + // Exemple : ajouter un script d'analyse Fathom tag. + { + tag: 'script', + attrs: { + src: 'https://cdn.usefathom.com/script.js', + 'data-site': 'MY-FATHOM-ID', + defer: true, + }, + }, + ], +}); +``` + +#### `HeadConfig` + +```ts +interface HeadConfig { + tag: string; + attrs?: Record<string, string | boolean | undefined>; + content?: string; +} +``` diff --git a/docs/src/content/docs/fr-FR/reference/frontmatter.md b/docs/src/content/docs/fr-FR/reference/frontmatter.md new file mode 100644 index 00000000..cdff1481 --- /dev/null +++ b/docs/src/content/docs/fr-FR/reference/frontmatter.md @@ -0,0 +1,119 @@ +--- +title: Frontmatter Reference +description: Une vue d'ensemble des champs frontmatter par défaut pris en charge par Starlight. +--- + +Vous pouvez personnaliser des pages Markdown et MDX individuelles dans Starlight en définissant des valeurs dans leur page de garde. Par exemple, une page normale peut définir les champs `title` et `description` : + +```md +--- +title: A propos de ce projet +description: En savoir plus sur le projet sur lequel je travaille. +--- + +Bienvenue sur la page "à propos" ! +``` + +## Champs de la page d'accueil + +### `title` (obligatoire) + +**type:** `string` + +Vous devez fournir un titre pour chaque page. Il sera affiché en haut de la page, dans les onglets du navigateur et dans les métadonnées de la page. + +### `description` + +**type:** `string` + +La description de la page est utilisée pour les métadonnées de la page et sera reprise par les moteurs de recherche et dans les aperçus des médias sociaux. + +### `editUrl` + +**type:** `string | boolean` + +Remplace la [configuration globale `editLink`](/fr-FR/reference/configuration/#editlink). Mettez `false` pour désactiver le lien "Editer la page" pour une page spécifique ou pour fournir une URL alternative où le contenu de cette page est éditable. + +### `head` + +**type:** [`HeadConfig[]`](/fr-FR/reference/configuration/#headconfig) + +Vous pouvez ajouter des balises supplémentaires au champ `<head>` de votre page en utilisant le champ `head` frontmatter. Cela signifie que vous pouvez ajouter des styles personnalisés, des métadonnées ou d'autres balises à une seule page. Similaire à [l'option globale `head`](/fr-FR/reference/configuration/#head). + +```md +--- +title: A propos de nous +head: + # Utiliser une balise <title> personnalisée + - tag: title + content: Titre personnalisé à propos de nous +--- +``` + +### `tableOfContents` + +**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` + +Remplace la [configuration globale `tableOfContents`](/fr-FR/reference/configuration/#tableofcontents). +Personnalisez les niveaux d'en-tête à inclure ou mettez `false` pour cacher la table des matières sur cette page. + +### `template` + +**type:** `'doc' | 'splash'` +**default:** `'doc'` + +Définit le modèle de mise en page pour cette page. +Les pages utilisent la mise en page `'doc'`' par défaut. +La valeur `'splash''` permet d'utiliser une mise en page plus large, sans barres latérales, conçue pour les pages d'atterrissage. + +### `hero` + +**type:** [`HeroConfig`](#heroconfig) + +Ajoute un composant héros en haut de la page. Fonctionne bien avec `template : splash`. + +Par exemple, cette configuration montre quelques options communes, y compris le chargement d'une image depuis votre dépôt. + +```md +--- +title: Ma page d'accueil +template: splash +hero: + title: 'Mon projet : Stellar Stuffer Sooner' + tagline: Emmenez vos affaires sur la lune et revenez-y en un clin d'œil. + image: + alt: Un logo aux couleurs vives et scintillantes + file: ../../assets/logo.png + actions: + - text: En savoir plus + link: /getting-started/ + icon: right-arrow + variant: primary + - text: Voir sur GitHub + link: https://github.com/astronaut/my-project + icon: external +--- +``` + +#### `HeroConfig` + +```ts +interface HeroConfig { + title?: string; + tagline?: string; + image?: { + alt?: string; + // Chemin relatif vers une image dans votre référentiel. + file?: string; + // HTML brut à utiliser dans l'emplacement de l'image. + // Il peut s'agir d'une balise `<img>` personnalisée ou d'une balise `<svg>` en ligne. + html?: string; + }; + actions?: Array<{ + text: string; + link: string; + variant: 'primary' | 'secondary' | 'minimal'; + icon: string; + }>; +} +``` diff --git a/docs/src/content/docs/fr-fr/environmental-impact.md b/docs/src/content/docs/fr-fr/environmental-impact.md deleted file mode 100644 index f9c8c919..00000000 --- a/docs/src/content/docs/fr-fr/environmental-impact.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Documents écologiques -description: Découvrez comment Starlight peut vous aider à créer des sites de documentation plus écologiques et à réduire votre empreinte carbone. ---- - -Les estimations de l'impact climatique de l'industrie du web varient entre [2 %][sf] et [4 % des émissions mondiales de carbone][bbc], ce qui équivaut à peu près aux émissions de l'industrie du transport aérien. -Le calcul de l'impact écologique d'un site web repose sur de nombreux facteurs complexes, mais ce guide contient quelques conseils pour réduire l'empreinte écologique de votre site documentaire. - -La bonne nouvelle, c'est que le choix de Starlight est un excellent début. -Selon le Website Carbon Calculator, ce site est [plus propre que 99 % des pages web testées][sl-carbon], produisant 0,01 g de CO₂ par page visitée. - -## Poids de la page - -Plus une page web transfère de données, plus elle nécessite de ressources énergétiques. -En avril 2023, la page web médiane demandait à l'utilisateur de télécharger plus de 2 000 Ko selon les [données de l'archive HTTP][http]. - -Starlight construit des pages aussi légères que possible. -Par exemple, lors de sa première visite, un utilisateur téléchargera moins de 50 Ko de données compressées, soit seulement 2,5 % de la médiane des archives HTTP. -Avec une bonne stratégie de mise en cache, les navigations suivantes peuvent télécharger jusqu'à 10 Ko. - -### Images - -Bien que Starlight fournisse une bonne base de référence, les images que vous ajoutez à vos pages de documentation peuvent rapidement augmenter le poids de vos pages. -Starlight utilise le [support d'actifs optimisés][assets] d'Astro pour optimiser les images locales dans vos fichiers Markdown et MDX. - -### Composants d'interface utilisateur - -Les composants construits avec des frameworks d'interface utilisateur tels que React ou Vue peuvent facilement ajouter de grandes quantités de JavaScript à une page. -Starlight étant construit sur Astro, les composants de ce type chargent **zéro JavaScript côté client par défaut** grâce à [Astro Islands][islands]. - -### Mise en cache - -La mise en cache est utilisée pour contrôler la durée pendant laquelle un navigateur stocke et réutilise les données qu'il a déjà téléchargées. -Une bonne stratégie de mise en cache permet à l'utilisateur d'obtenir un nouveau contenu dès qu'il est modifié, tout en évitant de télécharger inutilement le même contenu à plusieurs reprises lorsqu'il n'a pas changé. - -La façon la plus courante de configurer la mise en cache est d'utiliser l'en-tête HTTP [`Cache-Control`][cache]. -Lorsque vous utilisez Starlight, vous pouvez définir une longue durée de mise en cache pour tout ce qui se trouve dans le répertoire `/_astro/`. -Ce répertoire contient des fichiers CSS, JavaScript, et d'autres actifs intégrés qui peuvent être mis en cache pour toujours, réduisant ainsi les téléchargements inutiles : - -``` -Cache-Control: public, max-age=604800, immutable -``` - -La configuration de la mise en cache dépend de votre hébergeur. Par exemple, Vercel applique cette stratégie de mise en cache pour vous sans configuration nécessaire, tandis que vous pouvez définir des [en-têtes personnalisés pour Netlify][ntl-headers] en ajoutant un fichier `public/_headers` à votre projet : - -``` -/_astro/* - Cache-Control: public - Cache-Control: max-age=604800 - Cache-Control: immutable -``` - -[cache]: https://csswizardry.com/2019/03/cache-control-for-civilians/ -[ntl-headers]: https://docs.netlify.com/routing/headers/ - -## Consommation d'énergie - -La façon dont une page web est construite peut avoir un impact sur la puissance nécessaire pour fonctionner sur l'appareil d'un utilisateur. -En utilisant un minimum de JavaScript, Starlight réduit la puissance de traitement dont le téléphone, la tablette ou l'ordinateur d'un utilisateur a besoin pour charger et afficher les pages. - -Soyez vigilant lorsque vous ajoutez des fonctionnalités telles que des scripts de suivi analytique ou des contenus à forte teneur en JavaScript, comme des vidéos intégrées, car ils peuvent augmenter la consommation d'énergie de la page. -Si vous avez besoin d'analyses, envisagez de choisir une option légère comme [Cabin][cabin], [Fathom][fathom], ou [Plausible][plausible]. -Les vidéos intégrées comme celles de YouTube et de Vimeo peuvent être améliorées en attendant de [charger la vidéo lors de l'interaction avec l'utilisateur][lazy-video]. -Des paquets comme [`astro-embed`][embed] peuvent aider pour les services communs. - -:::tip[Le saviez-vous ?] -L'analyse et la compilation de JavaScript est l'une des tâches les plus coûteuses pour les navigateurs. -Par rapport au rendu d'une image JPEG de même taille, [le traitement de JavaScript peut prendre plus de 30 fois plus de temps][coût-de-js]. -::: - -[cabin]: https://withcabin.com/ -[fathom]: https://usefathom.com/ -[plausible]: https://plausible.io/ -[lazy-video]: https://web.dev/iframe-lazy-loading/ -[embed]: https://www.npmjs.com/package/astro-embed -[cost-of-js]: https://medium.com/dev-channel/the-cost-of-javascript-84009f51e99e - -## Hébergement - -Le lieu d'hébergement d'une page web peut avoir un impact important sur le degré de respect de l'environnement de votre site de documentation. -Les centres de données et les fermes de serveurs peuvent avoir un impact écologique important, notamment en raison de leur consommation élevée d'électricité et de leur utilisation intensive de l'eau. - -Le choix d'un hébergeur utilisant des énergies renouvelables se traduira par une réduction des émissions de carbone pour votre site. Le [Green Web Directory][gwb] est un outil qui peut vous aider à trouver des hébergeurs. - -[gwb]: https://www.thegreenwebfoundation.org/directory/ - -## Comparaisons - -Curieux de savoir comment les autres frameworks de documentation se comparent ? -Ces tests avec le [Website Carbon Calculator][wcc] comparent des pages similaires construites avec différents outils. - -| Framework | CO₂ par page visitée | -| --------------------------- | ------------------ | -| [Starlight][sl-carbon] | 0.01g | -| [VitePress][vp-carbon] | 0.05g | -| [Sphinx][sx-carbon] | 0.07g | -| [MkDocs][mk-carbon] | 0.10g | -| [Nextra][nx-carbon] | 0.11g | -| [Docusaurus][ds-carbon] | 0.24g | -| [Read the Docs][rtd-carbon] | 0.24g | -| [GitBook][gb-carbon] | 0.71g | - -<small>Données collectées le 14 mai 2023. Cliquez sur un lien pour voir les chiffres actualisés.</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/ -[sx-carbon]: https://www.websitecarbon.com/website/sphinx-doc-org-en-master-usage-quickstart-html/ -[mk-carbon]: https://www.websitecarbon.com/website/mkdocs-org-getting-started/ -[nx-carbon]: https://www.websitecarbon.com/website/nextra-site-docs-docs-theme-start/ -[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/ - -## Plus de ressources - -### Outils - -- [Website Carbon Calculator][wcc] -- [Ecograder](https://ecograder.com/) -- [WebPageTest Carbon Control](https://www.webpagetest.org/carbon-control/) -- [Ecoping](https://ecoping.earth/) - -### Articles et discussions - -- [“Building a greener web”](https://youtu.be/EfPoOt7T5lg), conférence de Michelle Barker -- [“Sustainable Web Development Strategies Within An Organization”](https://www.smashingmagazine.com/2022/10/sustainable-web-development-strategies-organization/), article par Michelle Barker -- [“A sustainable web for everyone”](https://2021.stateofthebrowser.com/speakers/tom-greenwood/), conférence de Tom Greenwood -- [“How Web Content Can Affect Power Usage”](https://webkit.org/blog/8970/how-web-content-can-affect-power-usage/), article de Benjamin Poulain et Simon Fraser - -[sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/ -[bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think -[http]: https://httparchive.org/reports/state-of-the-web -[assets]: https://docs.astro.build/en/guides/assets/ -[islands]: https://docs.astro.build/en/concepts/islands/ -[wcc]: https://www.websitecarbon.com/ diff --git a/docs/src/content/docs/fr-fr/getting-started.mdx b/docs/src/content/docs/fr-fr/getting-started.mdx deleted file mode 100644 index 383e7073..00000000 --- a/docs/src/content/docs/fr-fr/getting-started.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Mise en route -description: Apprenez à créer votre prochain site de documentation avec Starlight by Astro. ---- - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -:::caution[Work in progress] -Starlight est en début de développement. -Si vous trouvez quelque chose qui ne fonctionne pas, [ouvrez une issue sur GitHub](https://github.com/withastro/starlight/issues/new/choose) ou faites-le nous savoir sur [Discord](https://astro.build/chat). -::: - -## Créer un nouveau projet - -Starlight est un thème de documentation complet construit sur le framework [Astro](https://astro.build). - -Vous pouvez créer un nouveau projet Astro + Starlight en utilisant la commande suivante : - -<Tabs> -<TabItem label="npm"> - -```sh -# créer un nouveau projet avec npm -npm create astro@latest -- --template starlight -``` - -</TabItem> -<TabItem label="pnpm"> - -```sh -# créer un nouveau projet avec pnpm -pnpm create astro --template starlight -``` - -</TabItem> -<TabItem label="Yarn"> - -```sh -# créer un nouveau projet avec yarn -yarn create astro --template starlight -``` - -</TabItem> -</Tabs> - -Cela créera un nouveau [répertoire de projet](/guides/projet-structure/) avec tous les fichiers et configurations nécessaires pour votre site. - -:::tip[Voir en action] -Essayez Starlight dans votre navigateur : -[ouvrir le modèle sur StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics). -::: - -## Créer du contenu avec Starlight - -Starlight est prêt pour que vous puissiez ajouter du nouveau contenu, ou apporter vos fichiers existants ! - -### Formats de fichiers - -Starlight prend en charge la création de contenu en Markdown et MDX. (Vous pouvez ajouter la prise en charge de Markdoc en installant l'intégration expérimentale [Astro Markdoc integration](https://docs.astro.build/fr-fr/guides/integrations-guide/markdoc/).) - -### Ajouter des pages -Ajoutez automatiquement de nouvelles pages à votre site en créant des fichiers `.md` ou `.mdx` dans `src/content/docs/`. Ajoutez des sous-dossiers pour organiser vos fichiers, et pour créer plusieurs segments de chemin : - -```js -`src/content/docs/hello-world.md` -> `votre-site/hello-world` -`src/content/docs/guides/faq.md` -> `votre-site/guides/faq` -``` - -### Type-safe frontmatter - -Toutes les pages Starlight partagent un [ensemble commun de propriétés de présentation](/fr-fr/reference/frontmatter/) personnalisable pour contrôler l'apparence de la page : - -```md ---- -title: Bonjour, le monde ! -description: Ceci est une page de mon site web propulsé par Starlight. ---- -``` - -Si vous oubliez quelque chose d'important, Starlight vous le fera savoir. - -## Déployer votre site web Starlight - -Une fois que vous avez créé et personnalisé votre site Web Starlight, vous pouvez le déployer sur un serveur Web ou une plateforme d'hébergement de votre choix, y compris Netlify, Vercel, GitHub Pages et bien d'autres. - -[Pour en savoir plus sur le déploiement d'un site Astro, consultez la documentation Astro](https://docs.astro.build/fr/guides/deploy/) diff --git a/docs/src/content/docs/fr-fr/guides/authoring-content.md b/docs/src/content/docs/fr-fr/guides/authoring-content.md deleted file mode 100644 index 63258869..00000000 --- a/docs/src/content/docs/fr-fr/guides/authoring-content.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Création de contenu en Markdown -description: Un aperçu de la syntaxe Markdown prise en charge par Starlight. ---- - -Starlight prend en charge l'ensemble de la syntaxe [Markdown](https://daringfireball.net/projects/markdown/) dans les fichiers `.md` ainsi que la syntaxe frontale [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) pour définir des métadonnées telles qu'un titre et une description. - -Veillez à consulter les [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) ou les [Markdoc docs](https://markdoc.dev/docs/syntax) si vous utilisez ces formats de fichiers, car la prise en charge et l'utilisation de Markdown peuvent varier. - -## Styles en ligne - -Le texte peut être **gras**, _italique_, ou ~~barré~~. - -```md -Le texte peut être **gras**, _italique_, ou ~~barré~~. -``` - -Vous pouvez [faire un lien vers une autre page](/fr-fr/getting-started/). - -```md -Vous pouvez [faire un lien vers une autre page](/fr-fr/getting-started/). -``` - -Vous pouvez mettre en évidence le `code en ligne` à l'aide d'un astérisque. - -```md -Vous pouvez mettre en évidence le `code en ligne` à l'aide de barres de défilement. -``` - -## Images - -Les images dans Starlight utilisent la prise en charge intégrée des ressources optimisées d'Astro. - -Markdown et MDX supportent la syntaxe Markdown pour l'affichage des images qui inclut le texte alt pour les lecteurs d'écran et les technologies d'assistance. - -![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) - -```md -![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) -``` - -Les chemins d'accès relatifs aux images sont également supportés pour les images stockées localement dans votre projet. - -```md -// src/content/docs/page-1.md - -![Une fusée dans l'espace.](../../assets/images/rocket.svg) -``` - -## En-têtes - -Vous pouvez structurer le contenu à l'aide d'un titre. En Markdown, les titres sont indiqués par un nombre de `#` en début de ligne. - -### Comment structurer le contenu d'une page dans Starlight - -Starlight est configuré pour utiliser automatiquement le titre de votre page comme titre de premier niveau et inclura un titre "Aperçu" en haut de la table des matières de chaque page. Nous vous recommandons de commencer chaque page par un paragraphe de texte normal et d'utiliser des titres de page à partir de `<h2>` : - -```md ---- -title: Guide Markdown -description: Comment utiliser Markdown dans Starlight ---- - -Cette page décrit comment utiliser Markdown dans Starlight. - -## Styles en ligne - -## Titres - -``` - -### Liens d'ancrage automatiques pour les titres - -L'utilisation de titres en Markdown vous donnera automatiquement des liens d'ancrage afin que vous puissiez accéder directement à certaines sections de votre page : - -```md ---- -title: Ma page de contenu -description: Comment utiliser les liens d'ancrage intégrés de Starlight ---- -## Introduction - -Je peux faire un lien vers [ma conclusion](#conclusion) plus bas sur la même page. - -## Conclusion - -`https://my-site.com/page1/#introduction` renvoie directement à mon Introduction. -``` - -Les titres de niveau 2 (`<h2>`) et de niveau 3 (`<h3>`) apparaissent automatiquement dans la table des matières de la page. - -## Asides - -Les Asides (également connus sous le nom de "callouts") sont utiles pour afficher des informations secondaires à côté du contenu principal d'une page. - -Starlight fournit une syntaxe Markdown personnalisée pour le rendu des apartés. Les blocs d'apartés sont indiqués en utilisant une paire de triples points `:::` pour envelopper votre contenu, et peuvent être de type `note`, `tip`, `caution` ou `danger`. - -Vous pouvez imbriquer n'importe quel autre type de contenu Markdown à l'intérieur d'un aparté, mais les aparté sont mieux adaptés à des morceaux de contenu courts et concis. - -### Note aside - -:::note -Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : - -```sh -npm run create astro@latest --template starlight -``` - -::: - -````md -:::note -Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : - -```sh -npm run create astro@latest --template starlight -``` - -::: -```` - -### Titres personnalisés dans les asides - -Vous pouvez spécifier un titre personnalisé pour l'aparté entre crochets après le type d'aparté, par exemple `:::tip[Le saviez-vous ?]`. - -:::tip[Le saviez-vous ?] -Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). -::: - -```md -:::tip[Le saviez-vous ?] -Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). -::: -``` - -### Plus de types pour l'aside - -Les apartés de type Attention et Danger sont utiles pour attirer l'attention de l'utilisateur sur des détails qui pourraient le faire trébucher. -Si vous les utilisez souvent, c'est peut-être aussi le signe que la chose que vous documentez gagnerait à être repensée. - -:::caution -Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). -::: - -:::danger -Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. - -- Navigation claire -- Thème de couleurs configurable par l'utilisateur -- [Support i18n](/fr-fr/guides/i18n) - -::: - -```md -:::caution -Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). -::: - -:::danger -Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. - -- Navigation claire -- Thème de couleurs configurable par l'utilisateur -- [Support i18n](/fr-fr/guides/i18n) - -::: -``` - -## Blockquotes - -> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. -> -> Les guillemets sont indiqués par un `>` au début de chaque ligne. - -```md -> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. -> -> Les guillemets sont indiqués par un `>` au début de chaque ligne. -``` - -## Code blocks - -Un bloc de code est indiqué par un bloc avec trois crochets <code>```</code> au début et à la fin. Vous pouvez indiquer le langage de programmation utilisé après les premiers crochets. - -```js -// Code Javascript avec mise en évidence de la syntaxe. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` - -````md -```js -// Code Javascript avec mise en évidence de la syntaxe. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` -```` - -```md -Les longs blocs de code d'une seule ligne ne doivent pas être enveloppés. Ils doivent défiler horizontalement s'ils sont trop longs. Cette ligne devrait être suffisamment longue pour le démontrer. -``` - -## Autres fonctionnalités courantes de Markdown - -Starlight prend en charge toutes les autres syntaxes de rédaction Markdown, telles que les listes et les tableaux. Voir [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) pour un aperçu rapide de tous les éléments de la syntaxe Markdown. diff --git a/docs/src/content/docs/fr-fr/guides/components.mdx b/docs/src/content/docs/fr-fr/guides/components.mdx deleted file mode 100644 index 5e1000cf..00000000 --- a/docs/src/content/docs/fr-fr/guides/components.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Composants -description: Utilisation de composants dans MDX avec Starlight. ---- - -Les composants vous permettent de réutiliser facilement un élément d'interface utilisateur ou de style de manière cohérente. -Il peut s'agir par exemple d'une carte de lien ou d'une intégration YouTube. -Starlight prend en charge l'utilisation de composants dans les fichiers [MDX](https://mdxjs.com/) et fournit des composants courants que vous pouvez utiliser. - -[Pour en savoir plus sur la création de composants, consultez les Astro Docs](https://docs.astro.build/fr/core-concepts/astro-components/). - -## Utilisation d'un composant - -Vous pouvez utiliser un composant en l'important dans votre fichier MDX et en le rendant sous forme de balise JSX. -Ces balises ressemblent à des balises HTML mais commencent par une lettre majuscule correspondant au nom de votre déclaration `import` : - -```mdx ---- -# src/content/docs/index.mdx -title: Bienvenue dans ma documentation ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent> - Les composants peuvent également contenir du **contenu imbriqué**. -</AnotherComponent> -``` - -Starlight étant alimenté par Astro, vous pouvez ajouter la prise en charge des composants construits avec n'importe quel [cadre d'interface utilisateur pris en charge (React, Preact, Svelte, Vue, Solid, Lit et Alpine)](https://docs.astro.build/fr/core-concepts/framework-components/) dans vos fichiers MDX. -Pour en savoir plus sur [l'utilisation de composants dans MDX](https://docs.astro.build/fr/guides/markdown-content/#using-components-in-mdx), consultez la documentation Astro. - -## Composants intégrés - -Starlight fournit quelques composants intégrés pour les cas d'utilisation courants de la documentation. -Ces composants sont disponibles dans le paquet `@astrojs/starlight/components`. - -### Onglets - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Vous pouvez afficher une interface à onglets en utilisant les composants `<Tabs>` et `<TabItem>`. -Chaque `<TabItem>` doit avoir un `label` à afficher aux utilisateurs. - -```mdx -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> - <TabItem label="Moons">Io, Europa, Ganymede</TabItem> -</Tabs> -``` - -Le code ci-dessus génère les onglets suivants sur la page : - -<Tabs> - <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> - <TabItem label="Moons">Io, Europa, Ganymede</TabItem> -</Tabs> - -### Cards - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Vous pouvez afficher du contenu dans une boîte correspondant aux styles de Starlight en utilisant le composant `<Card>`. -Enveloppez plusieurs cartes dans le composant `<CardGrid>` pour afficher les cartes côte à côte lorsqu'il y a suffisamment d'espace. - -Une `<Card>` nécessite un `titre` et peut éventuellement inclure un attribut `icon` fixé au nom de [l'une des icônes intégrées de Starlight](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts). - -```mdx -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> - -<CardGrid> - <Card title="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Moons" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> - -<CardGrid> - <Card title="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Moons" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -Utilisez une grille de cartes sur votre page d'accueil pour afficher les principales caractéristiques de votre projet. -Ajoutez l'attribut `stagger` pour décaler verticalement la deuxième colonne de cartes et ajouter un intérêt visuel : - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: diff --git a/docs/src/content/docs/fr-fr/guides/i18n.mdx b/docs/src/content/docs/fr-fr/guides/i18n.mdx deleted file mode 100644 index 0bde4184..00000000 --- a/docs/src/content/docs/fr-fr/guides/i18n.mdx +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Internationalisation (i18n) -description: Apprenez à configurer votre site Starlight pour qu'il prenne en charge plusieurs langues. ---- - -import FileTree from '../../../components/file-tree.astro'; - -Starlight offre une prise en charge intégrée des sites multilingues, y compris le routage, le contenu de repli et la prise en charge complète des langues de droite à gauche (RTL). - -## Configurer i18n - -1. Indiquez à Starlight les langues que vous prenez en charge en passant `locales` et `defaultLocale` à l'intégration Starlight : - - ```js - // astro.config.mjs - import { defineConfig } from 'astro/config'; - import starlight from '@astrojs/starlight'; - - export default defineConfig({ - integrations: [ - starlight({ - title: 'My Docs', - // Définit l'anglais comme langue par défaut pour ce site. - defaultLocale: 'en', - locales: { - // Docs en anglais dans `src/content/docs/en/` - en: { - label: 'English', - }, - // Documentation en chinois simplifié dans `src/content/docs/zh/` - zh: { - label: '简体中文', - lang: 'zh-CN', - }, - // docs en arabe dans `src/content/docs/ar/` - ar: { - label: 'العربية', - dir: 'rtl', - }, - }, - }), - ], - }); - ``` - - Votre `defaultLocale` sera utilisé pour le contenu de repli et les étiquettes de l'interface utilisateur, donc choisissez la langue dans laquelle vous êtes le plus susceptible de commencer à écrire du contenu, ou pour laquelle vous avez déjà du contenu. - -2. Créez un répertoire pour chaque langue dans `src/content/docs/`. - Par exemple, pour la configuration montrée ci-dessus, créez les dossiers suivants : - - <FileTree> - - - src/ - - content/ - - docs/ - - ar/ - - en/ - - zh/ - - </FileTree> - -3. Vous pouvez maintenant ajouter des fichiers de contenu dans vos répertoires de langues. Utilisez le même nom de fichier pour associer les pages d'une langue à l'autre et profiter de l'ensemble des fonctionnalités i18n de Starlight, y compris le contenu de repli, les avis de traduction, etc. - - Par exemple, créez `ar/index.md` et `en/index.md` pour représenter la page d'accueil en arabe et en anglais respectivement. - -### Utiliser une racine locale - -Vous pouvez utiliser une racine locale pour servir une langue sans aucun préfixe i18n dans son chemin. Par exemple, si l'anglais est votre racine locale, le chemin d'une page en anglais ressemblera à `/about` au lieu de `/en/about`. - -Pour définir une racine locale, utilisez la clé `root` dans votre configuration `locales`. Si la racine locale est aussi la locale par défaut de votre contenu, supprimez `defaultLocale` ou donnez-lui la valeur `'root''. - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: 'My Docs', - defaultLocale: 'root', // optionnel - locales: { - root: { - label: 'English', - lang: 'en', // lang est nécessaire pour les locales de la racine - }, - zh: { - label: '简体中文', - lang: 'zh-CN', - }, - }, - }), - ], -}); -``` - -Lorsque vous utilisez une locale `root`, gardez les pages pour cette langue directement dans `src/content/docs/` au lieu d'un dossier dédié à la langue. Par exemple, voici les fichiers de la page d'accueil pour l'anglais et le chinois en utilisant la configuration ci-dessus : - -<FileTree> - -- src/ - - content/ - - docs/ - - **index.md** - - zh/ - - **index.md** - -</FileTree> - -#### Sites monolingues - -Par défaut, Starlight est un site monolingue (anglais). Pour créer un site monolingue dans une autre langue, définissez-la comme `root` dans votre configuration `locales` : - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: 'My Docs', - locales: { - root: { - label: '简体中文', - lang: 'zh-CN', - }, - }, - }), - ], -}); -``` - -Cela vous permet de remplacer la langue par défaut de Starlight sans activer d'autres fonctions d'internationalisation pour les sites multilingues, telles que le sélecteur de langue. - -## Contenu de remplacement - -Starlight s'attend à ce que vous créiez des pages équivalentes dans toutes vos langues. Par exemple, si vous avez un fichier `en/about.md`, créez un `about.md` pour chaque autre langue que vous supportez. Cela permet à Starlight de fournir un contenu de remplacement automatique pour les pages qui n'ont pas encore été traduites. - -Si une traduction n'est pas encore disponible pour une langue, Starlight affichera aux lecteurs le contenu de cette page dans la langue par défaut (définie via `defaultLocale`). Par exemple, si vous n'avez pas encore créé de version française de votre page À propos et que votre langue par défaut est l'anglais, les visiteurs de `/fr/about` verront le contenu anglais de `/en/about` avec un avis indiquant que cette page n'a pas encore été traduite. Cela vous permet d'ajouter du contenu dans votre langue par défaut et de le traduire progressivement lorsque vos traducteurs en ont le temps. - -## Traduire l'interface utilisateur de Starlight - -En plus d'héberger des fichiers de contenu traduits, Starlight vous permet de traduire les chaînes de l'interface utilisateur par défaut (par exemple, l'en-tête "Sur cette page" dans la table des matières) afin que vos lecteurs puissent découvrir votre site entièrement dans la langue sélectionnée. - -Les chaînes d'interface utilisateur traduites en anglais, allemand, japonais, portugais et espagnol sont fournies d'office, et nous acceptons les [contributions pour ajouter d'autres langues par défaut](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). - -Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collecte de données `i18n`. - -1. Configurez la collection de données `i18n` dans `src/content/config.ts` si elle n'est pas déjà configurée : - - ```js - // src/content/config.ts - import { defineCollection } from 'astro:content'; - import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; - - export const collections = { - docs: defineCollection({ schema: docsSchema() }), - i18n: defineCollection({ type: 'data', schema: i18nSchema() }), - }; - ``` - -2. Créez un fichier JSON dans `src/content/i18n/` pour chaque locale supplémentaire pour laquelle vous voulez fournir des chaînes de traduction pour l'interface utilisateur. - Par exemple, cela ajouterait des fichiers de traduction pour l'arabe et le chinois simplifié : - - <FileTree> - - - src/ - - content/ - - i18n/ - - ar.json - - zh-CN.json - - </FileTree> - -3. Ajoutez des traductions pour les clés que vous souhaitez traduire dans les fichiers JSON. Traduire uniquement les valeurs, en laissant les clés en anglais (e.g. `"search.label": "Buscar"`). - - Il s'agit des valeurs anglaises par défaut des chaînes de caractères existantes avec lesquelles Starlight est livré : - - ```json - { - "skipLink.label": "Aller au contenu", - "search.label": "rechercher", - "search.shortcutLabel": "(Presser / pour rechercher)", - "search.cancelLabel": "Annuler", - "themeSelect.accessibleLabel": "Selectionner le thème", - "themeSelect.dark": "Dark", - "themeSelect.light": "Light", - "themeSelect.auto": "Auto", - "languageSelect.accessibleLabel": "Selectionner la langue", - "menuButton.accessibleLabel": "Menu", - "sidebarNav.accessibleLabel": "Main", - "tableOfContents.onThisPage": "Sur cette page", - "tableOfContents.overview": "Vue d'ensemble", - "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", - "page.editLink": "Editer la page", - "page.lastUpdated": "Dernière mise à jour :", - "page.previousLink": "Suivant", - "page.nextLink": "Précédent" - } - ``` diff --git a/docs/src/content/docs/fr-fr/guides/project-structure.mdx b/docs/src/content/docs/fr-fr/guides/project-structure.mdx deleted file mode 100644 index cbb6855f..00000000 --- a/docs/src/content/docs/fr-fr/guides/project-structure.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Structure du projet -description: Apprenez à organiser les fichiers dans votre projet Starlight. ---- - -Ce guide vous montrera comment un projet Starlight est organisé et ce que font les différents fichiers de votre projet. - -Les projets Starlight suivent généralement la même structure de fichiers et de répertoires que les autres projets Astro. Voir [la documentation sur la structure des projets Astro](https://docs.astro.build/fr/core-concepts/project-structure/) pour plus de détails. - -## Fichiers et répertoires - -- `astro.config.mjs` — Le fichier de configuration d'Astro ; inclut l'intégration et la configuration de Starlight. -- `src/content/config.ts` — Fichier de configuration des collections de contenu ; ajoute les schémas de la matière première de Starlight à votre projet. -- `src/content/docs/` — Fichiers de contenu. Starlight transforme chaque fichier `.md`, `.mdx` ou `.mdoc` de ce répertoire en une page de votre site. -- `src/content/i18n/` (optionnel) — Données de traduction pour prendre en charge l'[internationalisation](/fr-fr/guides/i18n/). -- `src/` — Autre code source et fichiers (composants, styles, images, etc.) pour votre projet. -- `public/` — Actifs statiques (polices, favicon, PDFs, etc.) qui ne seront pas traités par Astro. - -## Exemple de contenu de projet - -Un répertoire de projet Starlight peut ressembler à ceci : - -import FileTree from '../../../components/file-tree.astro'; - -<FileTree> - -- public/ - - favicon.svg -- src/ - - assets/ - - logo.svg - - screenshot.jpg - - components/ - - CustomButton.astro - - InteractiveWidget.jsx - - content/ - - docs/ - - guides/ - - 01-getting-started.md - - 02-advanced.md - - index.mdx - - config.ts - - env.d.ts -- astro.config.mjs -- package.json -- tsconfig.json - -</FileTree> diff --git a/docs/src/content/docs/fr-fr/index.mdx b/docs/src/content/docs/fr-fr/index.mdx deleted file mode 100644 index 71fbca0e..00000000 --- a/docs/src/content/docs/fr-fr/index.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Starlight 🌟 Construire des sites de documentation avec Astro -description: Starlight vous aide à créer de magnifiques sites web de documentation très performants avec Astro. -template: splash -hero: - title: Faites briller vos documents avec Starlight - tagline: Tout ce dont vous avez besoin pour créer un excellent site web de documentation. Rapide, accessible et facile à utiliser. - image: - file: ../../../assets/hero-star.webp - actions: - - text: Mise en route - icon: right-arrow - variant: primary - link: /fr-fr/getting-started/ - - text: Voir sur GitHub - icon: external - link: https://github.com/withastro/starlight ---- - -import { CardGrid, Card } from '@astrojs/starlight/components'; -import AboutAstro from '../../components/about-astro.astro'; - -<CardGrid stagger> - <Card title="Une documentation qui enchante" icon="open-book"> - Comprend : Navigation dans le site, recherche, internationalisation, référencement naturel, typographie facile à lire, mise en évidence du code, mode sombre, etc. - </Card> - <Card title="Propulsé par Astro" icon="rocket"> - Exploitez toute la puissance et les performances d'Astro. Étendez Starlight avec vos intégrations et bibliothèques Astro préférées. - </Card> - <Card title="Markdown, Markdoc, et MDX" icon="document"> - Apportez votre langage de balisage préféré. Starlight vous offre une validation frontmatter intégrée avec la sécurité de type TypeScript. - </Card> - <Card title="Apportez vos propres composants d'interface utilisateur" icon="puzzle"> - Starlight est une solution de documentation complète, indépendante du cadre de travail. Étendez avec React, Vue, Svelte, Solid, et plus encore. - </Card> -</CardGrid> - -<AboutAstro title="Présenté par"> -Astro est le framework web tout-en-un conçu pour la vitesse. -Tirez votre contenu de n'importe où et déployez-le partout, le tout alimenté par vos composants et bibliothèques d'interface utilisateur préférés. - -[En savoir plus sur Astro](https://astro.build/) - -</AboutAstro> diff --git a/docs/src/content/docs/fr-fr/reference/configuration.md b/docs/src/content/docs/fr-fr/reference/configuration.md deleted file mode 100644 index 4e6ab2f9..00000000 --- a/docs/src/content/docs/fr-fr/reference/configuration.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -title: Référence de configuration -description: Une vue d'ensemble de toutes les options de configuration prises en charge par Starlight. ---- - -## Configuration de l'intégration `starlight` - -Starlight est une intégration construite sur le framework web [Astro](https://astro.build). Vous pouvez configurer votre projet dans le fichier de configuration Astro `astro.config.mjs` : - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: "Mon délicieux site de docs", - }), - ], -}); -``` - -Vous pouvez passer les options suivantes à l'intégration `starlight`. - -### `title` (obligatoire) - -**type:** `string` - -Définissez le titre de votre site web. Il sera utilisé dans les métadonnées et dans le titre de l'onglet du navigateur. - -### `description` - -**type:** `string` - -Définissez la description de votre site web. Utilisée dans les métadonnées partagées avec les moteurs de recherche dans la balise `<meta name="description">` si `description` n'est pas définie dans le frontmatter d'une page. - -### `logo` - -**type:** [`LogoConfig`](#logoconfig) - -Définit une image de logo à afficher dans la barre de navigation à côté ou à la place du titre du site. Vous pouvez soit définir une seule propriété `src`, soit définir des sources d'images séparées pour `light` et `dark`. - -```js -starlight({ - logo: { - src: '/src/assets/my-logo.svg', - }, -}); -``` - -#### `LogoConfig` - -```ts -type LogoConfig = { alt?: string; replacesTitle?: boolean } & ( - | { src: string } - | { light: string; dark: string } -); -``` - -### `tableOfContents` - -**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` -**default:** `{ minHeadingLevel: 2; maxHeadingLevel: 3; }` - -Configurez la table des matières affichée à droite de chaque page. Par défaut, les titres `<h2>` et `<h3>` seront inclus dans cette table des matières. - -### `editLink` - -**type:** `{ baseUrl: string }` - -Permet d'activer les liens "Modifier cette page" en définissant l'URL de base qu'ils doivent utiliser. Le lien final sera `editLink.baseUrl` + le chemin de la page actuelle. Par exemple, pour permettre l'édition de pages dans le repo `withastro/starlight` sur GitHub : - -```js -starlight({ - editLink: { - baseUrl: 'https://github.com/withastro/starlight/edit/main/', - }, -}); -``` - -Avec cette configuration, une page `/introduction` aurait un lien d'édition pointant vers `https://github.com/withastro/starlight/edit/main/src/docs/introduction.md`. - -### `sidebar` - -**type:** [`SidebarGroup[]`](#sidebargroup) - -Configure les éléments de navigation de la barre latérale de votre site. - -Une barre latérale est un tableau de groupes, chacun avec un `label` pour le groupe et un tableau `items` ou un objet de configuration `autogenerate`. - -Vous pouvez définir manuellement le contenu d'un groupe en utilisant `items`, qui est un tableau pouvant inclure des liens et des sous-groupes. Vous pouvez aussi générer automatiquement le contenu d'un groupe à partir d'un répertoire spécifique de votre documentation, en utilisant `autogenerate`. - -```js -starlight({ - sidebar: [ - // Un groupe intitulé "Commencer ici" contenant deux liens. - { - label: 'Commencer ici', - items: [ - { label: 'Introduction', link: '/intro' }, - { label: 'Etapes', link: '/next-steps' }, - ], - }, - // Un groupe qui renvoie à toutes les pages du répertoire de référence. - { - label: 'Référence', - autogenerate: { directory: 'reference' }, - }, - ], -}); -``` - -#### Tri - -Les groupes de barres latérales générées automatiquement sont triés par nom de fichier et par ordre alphabétique. -Par exemple, une page générée à partir de `astro.md` apparaîtrait au-dessus de la page de `starlight.md`. - -#### Traduire les étiquettes - -Si votre site est multilingue, le `label` de chaque élément est considéré comme étant dans la locale par défaut. Vous pouvez définir une propriété `translations` pour fournir des étiquettes pour les autres langues supportées : - -```js -sidebar: [ - // Un exemple de barre latérale avec des étiquettes traduites en anglais. - { - label: 'Commencer ici', - translations: { en: 'Start here' }, - items: [ - { - label: 'Bien démarrer', - translations: { en: 'Getting Started' }, - link: '/getting-started', - }, - { - label: 'Structure du projet', - translations: { en: 'Project Structure' }, - link: '/structure', - }, - ], - }, -]; -``` - -#### `SidebarGroup` - -```ts -type SidebarGroup = - | { - label: string; - translations?: Record<string, string>; - items: Array<LinkItem | SidebarGroup>; - } - | { - label: string; - translations?: Record<string, string>; - autogenerate: { - directory: string; - }; - }; -``` - -#### `LinkItem` - -```ts -interface LinkItem { - label: string; - link: string; -} -``` - -### `locales` - -**type:** `{ [dir: string]: LocaleConfig }` - -Configurez l'internationalisation (i18n) de votre site en définissant les `locales` supportées. - -Chaque entrée doit utiliser comme clé le répertoire dans lequel les fichiers de cette langue sont sauvegardés. - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: 'My Site', - // Définit l'anglais comme langue par défaut pour ce site. - defaultLocale: 'en', - locales: { - // Documentations en anglais danse trouve dans `src/content/docs/en/` - en: { - label: 'English', - }, - // Documentations en Chinois simplifié se trouve dans `src/content/docs/zh/` - zh: { - label: '简体中文', - lang: 'zh-CN', - }, - // Documentations en Arabe se trouve dans `src/content/docs/ar/` - ar: { - label: 'العربية', - dir: 'rtl', - }, - }, - }), - ], -}); -``` - -#### Options des paramètres linguistiques - -Vous pouvez définir les options suivantes pour chaque locale : - -##### `label` (obligatoire) - -**type:** `string` - -L'étiquette de cette langue à afficher aux utilisateurs, par exemple dans le sélecteur de langue. Le plus souvent, il s'agit du nom de la langue tel qu'un utilisateur de cette langue s'attendrait à le lire, par exemple `"English"`, `"العربية"`, ou `"简体中文"`. - -##### `lang` - -**type:** `string` - -La balise BCP-47 pour cette langue, par exemple `"en"`, `"ar"`, ou `"zh-CN"`. S'il n'est pas défini, le nom du répertoire de la langue sera utilisé par défaut. - -##### `dir` - -**type:** `'ltr' | 'rtl'` - -Le sens d'écriture de cette langue ; `"ltr"` pour gauche à droite (par défaut) ou `"rtl"` pour droite à gauche. - -#### Locale racine - -Vous pouvez servir la langue par défaut sans répertoire `/lang/` en définissant une locale `root` : - -```js -starlight({ - locales: { - root: { - label: 'English', - lang: 'en', - }, - fr: { - label: 'Français', - }, - }, -}); -``` - -Par exemple, cela vous permet de servir `/getting-started/` comme une route anglaise et d'utiliser `/fr/getting-started/` comme la page française équivalente. - -### `defaultLocale` - -**type:** `string` - -Définit la langue par défaut pour ce site. -La valeur doit correspondre à l'une des clés de votre objet [`locales`](#locales). -(Si votre langue par défaut est votre [root locale](#root-locale), vous pouvez sauter cette étape). - -La locale par défaut sera utilisée pour fournir un contenu de remplacement lorsque les traductions sont manquantes. - -### `social` - -**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }` - -Détails optionnels sur les comptes de médias sociaux pour ce site. L'ajout de l'un d'entre eux les affichera sous forme de liens iconiques dans l'en-tête du site. - -```js -starlight({ - social: { - discord: 'https://astro.build/chat', - github: 'https://github.com/withastro/starlight', - mastodon: 'https://m.webtoo.ls/@astro', - twitter: 'https://twitter.com/astrodotbuild', - }, -}); -``` - -### `customCss` - -**type:** `string[]` - -Fournit des fichiers CSS pour personnaliser l'aspect et la convivialité de votre site Starlight. - -Prend en charge les fichiers CSS locaux relatifs à la racine de votre projet, par exemple `'/src/custom.css'`, et les CSS que vous avez installés en tant que module npm, par exemple `'@fontsource/roboto'`. - -```js -starlight({ - customCss: ['/src/custom-styles.css', '@fontsource/roboto'], -}); -``` - -### `head` - -**type:** [`HeadConfig[]`](#headconfig) - -Ajoute des balises personnalisées au `<head>` de votre site Starlight. -Cela peut être utile pour ajouter des analyses et d'autres scripts et ressources tiers. - -```js -starlight({ - head: [ - // Exemple : ajouter un script d'analyse Fathom tag. - { - tag: 'script', - attrs: { - src: 'https://cdn.usefathom.com/script.js', - 'data-site': 'MY-FATHOM-ID', - defer: true, - }, - }, - ], -}); -``` - -#### `HeadConfig` - -```ts -interface HeadConfig { - tag: string; - attrs?: Record<string, string | boolean | undefined>; - content?: string; -} -``` diff --git a/docs/src/content/docs/fr-fr/reference/frontmatter.md b/docs/src/content/docs/fr-fr/reference/frontmatter.md deleted file mode 100644 index 6c64d0fe..00000000 --- a/docs/src/content/docs/fr-fr/reference/frontmatter.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Frontmatter Reference -description: Une vue d'ensemble des champs frontmatter par défaut pris en charge par Starlight. ---- - -Vous pouvez personnaliser des pages Markdown et MDX individuelles dans Starlight en définissant des valeurs dans leur page de garde. Par exemple, une page normale peut définir les champs `title` et `description` : - -```md ---- -title: A propos de ce projet -description: En savoir plus sur le projet sur lequel je travaille. ---- - -Bienvenue sur la page "à propos" ! -``` - -## Champs de la page d'accueil - -### `title` (obligatoire) - -**type:** `string` - -Vous devez fournir un titre pour chaque page. Il sera affiché en haut de la page, dans les onglets du navigateur et dans les métadonnées de la page. - -### `description` - -**type:** `string` - -La description de la page est utilisée pour les métadonnées de la page et sera reprise par les moteurs de recherche et dans les aperçus des médias sociaux. - -### `editUrl` - -**type:** `string | boolean` - -Remplace la [configuration globale `editLink`](/fr-fr/reference/configuration/#editlink). Mettez `false` pour désactiver le lien "Editer la page" pour une page spécifique ou pour fournir une URL alternative où le contenu de cette page est éditable. - -### `head` - -**type:** [`HeadConfig[]`](/fr-fr/reference/configuration/#headconfig) - -Vous pouvez ajouter des balises supplémentaires au champ `<head>` de votre page en utilisant le champ `head` frontmatter. Cela signifie que vous pouvez ajouter des styles personnalisés, des métadonnées ou d'autres balises à une seule page. Similaire à [l'option globale `head`](/fr-fr/reference/configuration/#head). - -```md ---- -title: A propos de nous -head: - # Utiliser une balise <title> personnalisée - - tag: title - content: Titre personnalisé à propos de nous ---- -``` - -### `tableOfContents` - -**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` - -Remplace la [configuration globale `tableOfContents`](/fr-fr/reference/configuration/#tableofcontents). -Personnalisez les niveaux d'en-tête à inclure ou mettez `false` pour cacher la table des matières sur cette page. - -### `template` - -**type:** `'doc' | 'splash'` -**default:** `'doc'` - -Set the layout template for this page. -Pages use the `'doc'` layout by default. -Set to `'splash'` to use a wider layout without any sidebars designed for landing pages. - -### `hero` - -**type:** [`HeroConfig`](#heroconfig) - -Ajoute un composant héros en haut de la page. Fonctionne bien avec `template : splash`. - -Par exemple, cette configuration montre quelques options communes, y compris le chargement d'une image depuis votre dépôt. - -```md ---- -title: Ma page d'accueil -template: splash -hero: - title: 'Mon projet : Stellar Stuffer Sooner' - tagline: Emmenez vos affaires sur la lune et revenez-y en un clin d'œil. - image: - alt: Un logo aux couleurs vives et scintillantes - file: ../../assets/logo.png - actions: - - text: En savoir plus - link: /getting-started/ - icon: right-arrow - variant: primary - - text: Voir sur GitHub - link: https://github.com/astronaut/my-project - icon: external ---- -``` - -#### `HeroConfig` - -```ts -interface HeroConfig { - title?: string; - tagline?: string; - image?: { - alt?: string; - // Chemin relatif vers une image dans votre référentiel. - file?: string; - // HTML brut à utiliser dans l'emplacement de l'image. - // Il peut s'agir d'une balise `<img>` personnalisée ou d'une balise `<svg>` en ligne. - html?: string; - }; - actions?: Array<{ - text: string; - link: string; - variant: 'primary' | 'secondary' | 'minimal'; - icon: string; - }>; -} -``` -- cgit From d8f56f0d5e504d8a24e02f7936eeb355436f3d80 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 19:10:06 +0200 Subject: Err path component --- docs/src/content/docs/fr-FR/guides/i18n.mdx | 2 +- docs/src/content/docs/fr-FR/guides/project-structure.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/fr-FR/guides/i18n.mdx b/docs/src/content/docs/fr-FR/guides/i18n.mdx index 0bde4184..eb64d03f 100644 --- a/docs/src/content/docs/fr-FR/guides/i18n.mdx +++ b/docs/src/content/docs/fr-FR/guides/i18n.mdx @@ -3,7 +3,7 @@ title: Internationalisation (i18n) description: Apprenez à configurer votre site Starlight pour qu'il prenne en charge plusieurs langues. --- -import FileTree from '../../../components/file-tree.astro'; +import FileTree from '../../../../components/file-tree.astro'; Starlight offre une prise en charge intégrée des sites multilingues, y compris le routage, le contenu de repli et la prise en charge complète des langues de droite à gauche (RTL). diff --git a/docs/src/content/docs/fr-FR/guides/project-structure.mdx b/docs/src/content/docs/fr-FR/guides/project-structure.mdx index 4d301614..4ef16853 100644 --- a/docs/src/content/docs/fr-FR/guides/project-structure.mdx +++ b/docs/src/content/docs/fr-FR/guides/project-structure.mdx @@ -20,7 +20,7 @@ Les projets Starlight suivent généralement la même structure de fichiers et d Un répertoire de projet Starlight peut ressembler à ceci : -import FileTree from '../../../components/file-tree.astro'; +import FileTree from '../../../../components/file-tree.astro'; <FileTree> -- cgit From c7d067b531895d7c03feeb956b0bbe3546151082 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 19:11:52 +0200 Subject: Missed index.mdx for the component path --- docs/src/content/docs/fr-FR/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/fr-FR/index.mdx b/docs/src/content/docs/fr-FR/index.mdx index 14966082..1bdcaac5 100644 --- a/docs/src/content/docs/fr-FR/index.mdx +++ b/docs/src/content/docs/fr-FR/index.mdx @@ -18,7 +18,7 @@ hero: --- import { CardGrid, Card } from '@astrojs/starlight/components'; -import AboutAstro from '../../components/about-astro.astro'; +import AboutAstro from '../../../components/about-astro.astro'; <CardGrid stagger> <Card title="Une documentation qui enchante" icon="open-book"> -- cgit From 3d418ae816ab5272825bc07a1c9110c662f3618b Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 19:25:08 +0200 Subject: "fr-FR" to "fr" --- docs/astro.config.mjs | 12 +- .../src/content/docs/fr-FR/environmental-impact.md | 135 --------- docs/src/content/docs/fr-FR/getting-started.mdx | 86 ------ .../content/docs/fr-FR/guides/authoring-content.md | 209 ------------- docs/src/content/docs/fr-FR/guides/components.mdx | 111 ------- docs/src/content/docs/fr-FR/guides/i18n.mdx | 201 ------------- .../docs/fr-FR/guides/project-structure.mdx | 48 --- docs/src/content/docs/fr-FR/index.mdx | 44 --- .../content/docs/fr-FR/reference/configuration.md | 326 --------------------- .../content/docs/fr-FR/reference/frontmatter.md | 119 -------- docs/src/content/docs/fr/environmental-impact.md | 135 +++++++++ docs/src/content/docs/fr/getting-started.mdx | 86 ++++++ .../content/docs/fr/guides/authoring-content.md | 209 +++++++++++++ docs/src/content/docs/fr/guides/components.mdx | 111 +++++++ docs/src/content/docs/fr/guides/i18n.mdx | 201 +++++++++++++ .../content/docs/fr/guides/project-structure.mdx | 48 +++ docs/src/content/docs/fr/index.mdx | 44 +++ .../src/content/docs/fr/reference/configuration.md | 326 +++++++++++++++++++++ docs/src/content/docs/fr/reference/frontmatter.md | 119 ++++++++ 19 files changed, 1285 insertions(+), 1285 deletions(-) delete mode 100644 docs/src/content/docs/fr-FR/environmental-impact.md delete mode 100644 docs/src/content/docs/fr-FR/getting-started.mdx delete mode 100644 docs/src/content/docs/fr-FR/guides/authoring-content.md delete mode 100644 docs/src/content/docs/fr-FR/guides/components.mdx delete mode 100644 docs/src/content/docs/fr-FR/guides/i18n.mdx delete mode 100644 docs/src/content/docs/fr-FR/guides/project-structure.mdx delete mode 100644 docs/src/content/docs/fr-FR/index.mdx delete mode 100644 docs/src/content/docs/fr-FR/reference/configuration.md delete mode 100644 docs/src/content/docs/fr-FR/reference/frontmatter.md create mode 100644 docs/src/content/docs/fr/environmental-impact.md create mode 100644 docs/src/content/docs/fr/getting-started.mdx create mode 100644 docs/src/content/docs/fr/guides/authoring-content.md create mode 100644 docs/src/content/docs/fr/guides/components.mdx create mode 100644 docs/src/content/docs/fr/guides/i18n.mdx create mode 100644 docs/src/content/docs/fr/guides/project-structure.mdx create mode 100644 docs/src/content/docs/fr/index.mdx create mode 100644 docs/src/content/docs/fr/reference/configuration.md create mode 100644 docs/src/content/docs/fr/reference/frontmatter.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 47770e54..277176ef 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -44,7 +44,7 @@ export default defineConfig({ de: { label: 'Deutsch', lang: 'de' }, es: { label: 'Español', lang: 'es' }, ja: { label: '日本語', lang: 'ja' }, - "fr-FR": { label: 'Français', lang: 'fr-FR' }, + fr: { label: 'Français', lang: 'fr' }, }, sidebar: [ { @@ -53,24 +53,24 @@ export default defineConfig({ de: 'Beginne hier', es: 'Comienza aqui', ja: 'ここからはじめる', - "fr-FR": 'Commencez ici', + fr: 'Commencez ici', }, items: [ { label: 'Getting Started', link: 'getting-started', - translations: { es: "Empezando", ja: '入門', "fr-FR": 'Mise en route' }, + translations: { es: "Empezando", ja: '入門', fr: 'Mise en route' }, }, { label: 'Environmental Impact', link: 'environmental-impact', - translations: { es: "Documentación ecológica", ja: '環境への負荷', "fr-FR": 'Impact environnemental' }, + translations: { es: "Documentación ecológica", ja: '環境への負荷', fr: 'Impact environnemental' }, }, ], }, { label: 'Guides', - translations: { de: 'Anleitungen', es: 'Guías', ja: 'ガイド', "fr-FR": 'Guides' }, + translations: { de: 'Anleitungen', es: 'Guías', ja: 'ガイド', fr: 'Guides' }, autogenerate: { directory: 'guides' }, }, { @@ -79,7 +79,7 @@ export default defineConfig({ de: 'Referenz', es: 'Referencias', ja: 'リファレンス', - "fr-FR": 'Référence', + fr: 'Référence', }, autogenerate: { directory: 'reference' }, }, diff --git a/docs/src/content/docs/fr-FR/environmental-impact.md b/docs/src/content/docs/fr-FR/environmental-impact.md deleted file mode 100644 index f9c8c919..00000000 --- a/docs/src/content/docs/fr-FR/environmental-impact.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Documents écologiques -description: Découvrez comment Starlight peut vous aider à créer des sites de documentation plus écologiques et à réduire votre empreinte carbone. ---- - -Les estimations de l'impact climatique de l'industrie du web varient entre [2 %][sf] et [4 % des émissions mondiales de carbone][bbc], ce qui équivaut à peu près aux émissions de l'industrie du transport aérien. -Le calcul de l'impact écologique d'un site web repose sur de nombreux facteurs complexes, mais ce guide contient quelques conseils pour réduire l'empreinte écologique de votre site documentaire. - -La bonne nouvelle, c'est que le choix de Starlight est un excellent début. -Selon le Website Carbon Calculator, ce site est [plus propre que 99 % des pages web testées][sl-carbon], produisant 0,01 g de CO₂ par page visitée. - -## Poids de la page - -Plus une page web transfère de données, plus elle nécessite de ressources énergétiques. -En avril 2023, la page web médiane demandait à l'utilisateur de télécharger plus de 2 000 Ko selon les [données de l'archive HTTP][http]. - -Starlight construit des pages aussi légères que possible. -Par exemple, lors de sa première visite, un utilisateur téléchargera moins de 50 Ko de données compressées, soit seulement 2,5 % de la médiane des archives HTTP. -Avec une bonne stratégie de mise en cache, les navigations suivantes peuvent télécharger jusqu'à 10 Ko. - -### Images - -Bien que Starlight fournisse une bonne base de référence, les images que vous ajoutez à vos pages de documentation peuvent rapidement augmenter le poids de vos pages. -Starlight utilise le [support d'actifs optimisés][assets] d'Astro pour optimiser les images locales dans vos fichiers Markdown et MDX. - -### Composants d'interface utilisateur - -Les composants construits avec des frameworks d'interface utilisateur tels que React ou Vue peuvent facilement ajouter de grandes quantités de JavaScript à une page. -Starlight étant construit sur Astro, les composants de ce type chargent **zéro JavaScript côté client par défaut** grâce à [Astro Islands][islands]. - -### Mise en cache - -La mise en cache est utilisée pour contrôler la durée pendant laquelle un navigateur stocke et réutilise les données qu'il a déjà téléchargées. -Une bonne stratégie de mise en cache permet à l'utilisateur d'obtenir un nouveau contenu dès qu'il est modifié, tout en évitant de télécharger inutilement le même contenu à plusieurs reprises lorsqu'il n'a pas changé. - -La façon la plus courante de configurer la mise en cache est d'utiliser l'en-tête HTTP [`Cache-Control`][cache]. -Lorsque vous utilisez Starlight, vous pouvez définir une longue durée de mise en cache pour tout ce qui se trouve dans le répertoire `/_astro/`. -Ce répertoire contient des fichiers CSS, JavaScript, et d'autres actifs intégrés qui peuvent être mis en cache pour toujours, réduisant ainsi les téléchargements inutiles : - -``` -Cache-Control: public, max-age=604800, immutable -``` - -La configuration de la mise en cache dépend de votre hébergeur. Par exemple, Vercel applique cette stratégie de mise en cache pour vous sans configuration nécessaire, tandis que vous pouvez définir des [en-têtes personnalisés pour Netlify][ntl-headers] en ajoutant un fichier `public/_headers` à votre projet : - -``` -/_astro/* - Cache-Control: public - Cache-Control: max-age=604800 - Cache-Control: immutable -``` - -[cache]: https://csswizardry.com/2019/03/cache-control-for-civilians/ -[ntl-headers]: https://docs.netlify.com/routing/headers/ - -## Consommation d'énergie - -La façon dont une page web est construite peut avoir un impact sur la puissance nécessaire pour fonctionner sur l'appareil d'un utilisateur. -En utilisant un minimum de JavaScript, Starlight réduit la puissance de traitement dont le téléphone, la tablette ou l'ordinateur d'un utilisateur a besoin pour charger et afficher les pages. - -Soyez vigilant lorsque vous ajoutez des fonctionnalités telles que des scripts de suivi analytique ou des contenus à forte teneur en JavaScript, comme des vidéos intégrées, car ils peuvent augmenter la consommation d'énergie de la page. -Si vous avez besoin d'analyses, envisagez de choisir une option légère comme [Cabin][cabin], [Fathom][fathom], ou [Plausible][plausible]. -Les vidéos intégrées comme celles de YouTube et de Vimeo peuvent être améliorées en attendant de [charger la vidéo lors de l'interaction avec l'utilisateur][lazy-video]. -Des paquets comme [`astro-embed`][embed] peuvent aider pour les services communs. - -:::tip[Le saviez-vous ?] -L'analyse et la compilation de JavaScript est l'une des tâches les plus coûteuses pour les navigateurs. -Par rapport au rendu d'une image JPEG de même taille, [le traitement de JavaScript peut prendre plus de 30 fois plus de temps][coût-de-js]. -::: - -[cabin]: https://withcabin.com/ -[fathom]: https://usefathom.com/ -[plausible]: https://plausible.io/ -[lazy-video]: https://web.dev/iframe-lazy-loading/ -[embed]: https://www.npmjs.com/package/astro-embed -[cost-of-js]: https://medium.com/dev-channel/the-cost-of-javascript-84009f51e99e - -## Hébergement - -Le lieu d'hébergement d'une page web peut avoir un impact important sur le degré de respect de l'environnement de votre site de documentation. -Les centres de données et les fermes de serveurs peuvent avoir un impact écologique important, notamment en raison de leur consommation élevée d'électricité et de leur utilisation intensive de l'eau. - -Le choix d'un hébergeur utilisant des énergies renouvelables se traduira par une réduction des émissions de carbone pour votre site. Le [Green Web Directory][gwb] est un outil qui peut vous aider à trouver des hébergeurs. - -[gwb]: https://www.thegreenwebfoundation.org/directory/ - -## Comparaisons - -Curieux de savoir comment les autres frameworks de documentation se comparent ? -Ces tests avec le [Website Carbon Calculator][wcc] comparent des pages similaires construites avec différents outils. - -| Framework | CO₂ par page visitée | -| --------------------------- | ------------------ | -| [Starlight][sl-carbon] | 0.01g | -| [VitePress][vp-carbon] | 0.05g | -| [Sphinx][sx-carbon] | 0.07g | -| [MkDocs][mk-carbon] | 0.10g | -| [Nextra][nx-carbon] | 0.11g | -| [Docusaurus][ds-carbon] | 0.24g | -| [Read the Docs][rtd-carbon] | 0.24g | -| [GitBook][gb-carbon] | 0.71g | - -<small>Données collectées le 14 mai 2023. Cliquez sur un lien pour voir les chiffres actualisés.</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/ -[sx-carbon]: https://www.websitecarbon.com/website/sphinx-doc-org-en-master-usage-quickstart-html/ -[mk-carbon]: https://www.websitecarbon.com/website/mkdocs-org-getting-started/ -[nx-carbon]: https://www.websitecarbon.com/website/nextra-site-docs-docs-theme-start/ -[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/ - -## Plus de ressources - -### Outils - -- [Website Carbon Calculator][wcc] -- [Ecograder](https://ecograder.com/) -- [WebPageTest Carbon Control](https://www.webpagetest.org/carbon-control/) -- [Ecoping](https://ecoping.earth/) - -### Articles et discussions - -- [“Building a greener web”](https://youtu.be/EfPoOt7T5lg), conférence de Michelle Barker -- [“Sustainable Web Development Strategies Within An Organization”](https://www.smashingmagazine.com/2022/10/sustainable-web-development-strategies-organization/), article par Michelle Barker -- [“A sustainable web for everyone”](https://2021.stateofthebrowser.com/speakers/tom-greenwood/), conférence de Tom Greenwood -- [“How Web Content Can Affect Power Usage”](https://webkit.org/blog/8970/how-web-content-can-affect-power-usage/), article de Benjamin Poulain et Simon Fraser - -[sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/ -[bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think -[http]: https://httparchive.org/reports/state-of-the-web -[assets]: https://docs.astro.build/en/guides/assets/ -[islands]: https://docs.astro.build/en/concepts/islands/ -[wcc]: https://www.websitecarbon.com/ diff --git a/docs/src/content/docs/fr-FR/getting-started.mdx b/docs/src/content/docs/fr-FR/getting-started.mdx deleted file mode 100644 index b40b1c39..00000000 --- a/docs/src/content/docs/fr-FR/getting-started.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Mise en route -description: Apprenez à créer votre prochain site de documentation avec Starlight by Astro. ---- - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -:::caution[Work in progress] -Starlight est en début de développement. -Si vous trouvez quelque chose qui ne fonctionne pas, [ouvrez une issue sur GitHub](https://github.com/withastro/starlight/issues/new/choose) ou faites-le nous savoir sur [Discord](https://astro.build/chat). -::: - -## Créer un nouveau projet - -Starlight est un thème de documentation complet construit sur le framework [Astro](https://astro.build). - -Vous pouvez créer un nouveau projet Astro + Starlight en utilisant la commande suivante : - -<Tabs> -<TabItem label="npm"> - -```sh -# créer un nouveau projet avec npm -npm create astro@latest -- --template starlight -``` - -</TabItem> -<TabItem label="pnpm"> - -```sh -# créer un nouveau projet avec pnpm -pnpm create astro --template starlight -``` - -</TabItem> -<TabItem label="Yarn"> - -```sh -# créer un nouveau projet avec yarn -yarn create astro --template starlight -``` - -</TabItem> -</Tabs> - -Cela créera un nouveau [répertoire de projet](/fr-FR/guides/projet-structure/) avec tous les fichiers et configurations nécessaires pour votre site. - -:::tip[Voir en action] -Essayez Starlight dans votre navigateur : -[ouvrir le modèle sur StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics). -::: - -## Créer du contenu avec Starlight - -Starlight est prêt pour que vous puissiez ajouter du nouveau contenu, ou apporter vos fichiers existants ! - -### Formats de fichiers - -Starlight prend en charge la création de contenu en Markdown et MDX. (Vous pouvez ajouter la prise en charge de Markdoc en installant l'intégration expérimentale [Astro Markdoc integration](https://docs.astro.build/fr/guides/integrations-guide/markdoc/).) - -### Ajouter des pages -Ajoutez automatiquement de nouvelles pages à votre site en créant des fichiers `.md` ou `.mdx` dans `src/content/docs/`. Ajoutez des sous-dossiers pour organiser vos fichiers, et pour créer plusieurs segments de chemin : - -```js -`src/content/docs/hello-world.md` -> `votre-site/hello-world` -`src/content/docs/guides/faq.md` -> `votre-site/guides/faq` -``` - -### Type-safe frontmatter - -Toutes les pages Starlight partagent un [ensemble commun de propriétés de présentation](/fr-FR/reference/frontmatter/) personnalisable pour contrôler l'apparence de la page : - -```md ---- -title: Bonjour, le monde ! -description: Ceci est une page de mon site web propulsé par Starlight. ---- -``` - -Si vous oubliez quelque chose d'important, Starlight vous le fera savoir. - -## Déployer votre site web Starlight - -Une fois que vous avez créé et personnalisé votre site Web Starlight, vous pouvez le déployer sur un serveur Web ou une plateforme d'hébergement de votre choix, y compris Netlify, Vercel, GitHub Pages et bien d'autres. - -[Pour en savoir plus sur le déploiement d'un site Astro, consultez la documentation Astro](https://docs.astro.build/fr/guides/deploy/) diff --git a/docs/src/content/docs/fr-FR/guides/authoring-content.md b/docs/src/content/docs/fr-FR/guides/authoring-content.md deleted file mode 100644 index 1e6da7b2..00000000 --- a/docs/src/content/docs/fr-FR/guides/authoring-content.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Création de contenu en Markdown -description: Un aperçu de la syntaxe Markdown prise en charge par Starlight. ---- - -Starlight prend en charge l'ensemble de la syntaxe [Markdown](https://daringfireball.net/projects/markdown/) dans les fichiers `.md` ainsi que la syntaxe frontale [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) pour définir des métadonnées telles qu'un titre et une description. - -Veillez à consulter les [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) ou les [Markdoc docs](https://markdoc.dev/docs/syntax) si vous utilisez ces formats de fichiers, car la prise en charge et l'utilisation de Markdown peuvent varier. - -## Styles en ligne - -Le texte peut être **gras**, _italique_, ou ~~barré~~. - -```md -Le texte peut être **gras**, _italique_, ou ~~barré~~. -``` - -Vous pouvez [faire un lien vers une autre page](/fr-FR/getting-started/). - -```md -Vous pouvez [faire un lien vers une autre page](/fr-FR/getting-started/). -``` - -Vous pouvez mettre en évidence le `code en ligne` à l'aide d'un astérisque. - -```md -Vous pouvez mettre en évidence le `code en ligne` à l'aide de barres de défilement. -``` - -## Images - -Les images dans Starlight utilisent la prise en charge intégrée des ressources optimisées d'Astro. - -Markdown et MDX supportent la syntaxe Markdown pour l'affichage des images qui inclut le texte alt pour les lecteurs d'écran et les technologies d'assistance. - -![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) - -```md -![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) -``` - -Les chemins d'accès relatifs aux images sont également supportés pour les images stockées localement dans votre projet. - -```md -// src/content/docs/page-1.md - -![Une fusée dans l'espace.](../../assets/images/rocket.svg) -``` - -## En-têtes - -Vous pouvez structurer le contenu à l'aide d'un titre. En Markdown, les titres sont indiqués par un nombre de `#` en début de ligne. - -### Comment structurer le contenu d'une page dans Starlight - -Starlight est configuré pour utiliser automatiquement le titre de votre page comme titre de premier niveau et inclura un titre "Aperçu" en haut de la table des matières de chaque page. Nous vous recommandons de commencer chaque page par un paragraphe de texte normal et d'utiliser des titres de page à partir de `<h2>` : - -```md ---- -title: Guide Markdown -description: Comment utiliser Markdown dans Starlight ---- - -Cette page décrit comment utiliser Markdown dans Starlight. - -## Styles en ligne - -## Titres - -``` - -### Liens d'ancrage automatiques pour les titres - -L'utilisation de titres en Markdown vous donnera automatiquement des liens d'ancrage afin que vous puissiez accéder directement à certaines sections de votre page : - -```md ---- -title: Ma page de contenu -description: Comment utiliser les liens d'ancrage intégrés de Starlight ---- -## Introduction - -Je peux faire un lien vers [ma conclusion](#conclusion) plus bas sur la même page. - -## Conclusion - -`https://my-site.com/page1/#introduction` renvoie directement à mon Introduction. -``` - -Les titres de niveau 2 (`<h2>`) et de niveau 3 (`<h3>`) apparaissent automatiquement dans la table des matières de la page. - -## Asides - -Les Asides (également connus sous le nom de "callouts") sont utiles pour afficher des informations secondaires à côté du contenu principal d'une page. - -Starlight fournit une syntaxe Markdown personnalisée pour le rendu des apartés. Les blocs d'apartés sont indiqués en utilisant une paire de triples points `:::` pour envelopper votre contenu, et peuvent être de type `note`, `tip`, `caution` ou `danger`. - -Vous pouvez imbriquer n'importe quel autre type de contenu Markdown à l'intérieur d'un aparté, mais les aparté sont mieux adaptés à des morceaux de contenu courts et concis. - -### Note aside - -:::note -Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : - -```sh -npm run create astro@latest --template starlight -``` - -::: - -````md -:::note -Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : - -```sh -npm run create astro@latest --template starlight -``` - -::: -```` - -### Titres personnalisés dans les asides - -Vous pouvez spécifier un titre personnalisé pour l'aparté entre crochets après le type d'aparté, par exemple `:::tip[Le saviez-vous ?]`. - -:::tip[Le saviez-vous ?] -Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). -::: - -```md -:::tip[Le saviez-vous ?] -Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). -::: -``` - -### Plus de types pour l'aside - -Les apartés de type Attention et Danger sont utiles pour attirer l'attention de l'utilisateur sur des détails qui pourraient le faire trébucher. -Si vous les utilisez souvent, c'est peut-être aussi le signe que la chose que vous documentez gagnerait à être repensée. - -:::caution -Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). -::: - -:::danger -Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. - -- Navigation claire -- Thème de couleurs configurable par l'utilisateur -- [Support i18n](/fr-FR/guides/i18n) - -::: - -```md -:::caution -Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). -::: - -:::danger -Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. - -- Navigation claire -- Thème de couleurs configurable par l'utilisateur -- [Support i18n](/fr-FR/guides/i18n) - -::: -``` - -## Blockquotes - -> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. -> -> Les guillemets sont indiqués par un `>` au début de chaque ligne. - -```md -> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. -> -> Les guillemets sont indiqués par un `>` au début de chaque ligne. -``` - -## Code blocks - -Un bloc de code est indiqué par un bloc avec trois crochets <code>```</code> au début et à la fin. Vous pouvez indiquer le langage de programmation utilisé après les premiers crochets. - -```js -// Code Javascript avec mise en évidence de la syntaxe. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` - -````md -```js -// Code Javascript avec mise en évidence de la syntaxe. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` -```` - -```md -Les longs blocs de code d'une seule ligne ne doivent pas être enveloppés. Ils doivent défiler horizontalement s'ils sont trop longs. Cette ligne devrait être suffisamment longue pour le démontrer. -``` - -## Autres fonctionnalités courantes de Markdown - -Starlight prend en charge toutes les autres syntaxes de rédaction Markdown, telles que les listes et les tableaux. Voir [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) pour un aperçu rapide de tous les éléments de la syntaxe Markdown. diff --git a/docs/src/content/docs/fr-FR/guides/components.mdx b/docs/src/content/docs/fr-FR/guides/components.mdx deleted file mode 100644 index 5e1000cf..00000000 --- a/docs/src/content/docs/fr-FR/guides/components.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Composants -description: Utilisation de composants dans MDX avec Starlight. ---- - -Les composants vous permettent de réutiliser facilement un élément d'interface utilisateur ou de style de manière cohérente. -Il peut s'agir par exemple d'une carte de lien ou d'une intégration YouTube. -Starlight prend en charge l'utilisation de composants dans les fichiers [MDX](https://mdxjs.com/) et fournit des composants courants que vous pouvez utiliser. - -[Pour en savoir plus sur la création de composants, consultez les Astro Docs](https://docs.astro.build/fr/core-concepts/astro-components/). - -## Utilisation d'un composant - -Vous pouvez utiliser un composant en l'important dans votre fichier MDX et en le rendant sous forme de balise JSX. -Ces balises ressemblent à des balises HTML mais commencent par une lettre majuscule correspondant au nom de votre déclaration `import` : - -```mdx ---- -# src/content/docs/index.mdx -title: Bienvenue dans ma documentation ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent> - Les composants peuvent également contenir du **contenu imbriqué**. -</AnotherComponent> -``` - -Starlight étant alimenté par Astro, vous pouvez ajouter la prise en charge des composants construits avec n'importe quel [cadre d'interface utilisateur pris en charge (React, Preact, Svelte, Vue, Solid, Lit et Alpine)](https://docs.astro.build/fr/core-concepts/framework-components/) dans vos fichiers MDX. -Pour en savoir plus sur [l'utilisation de composants dans MDX](https://docs.astro.build/fr/guides/markdown-content/#using-components-in-mdx), consultez la documentation Astro. - -## Composants intégrés - -Starlight fournit quelques composants intégrés pour les cas d'utilisation courants de la documentation. -Ces composants sont disponibles dans le paquet `@astrojs/starlight/components`. - -### Onglets - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Vous pouvez afficher une interface à onglets en utilisant les composants `<Tabs>` et `<TabItem>`. -Chaque `<TabItem>` doit avoir un `label` à afficher aux utilisateurs. - -```mdx -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> - <TabItem label="Moons">Io, Europa, Ganymede</TabItem> -</Tabs> -``` - -Le code ci-dessus génère les onglets suivants sur la page : - -<Tabs> - <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> - <TabItem label="Moons">Io, Europa, Ganymede</TabItem> -</Tabs> - -### Cards - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Vous pouvez afficher du contenu dans une boîte correspondant aux styles de Starlight en utilisant le composant `<Card>`. -Enveloppez plusieurs cartes dans le composant `<CardGrid>` pour afficher les cartes côte à côte lorsqu'il y a suffisamment d'espace. - -Une `<Card>` nécessite un `titre` et peut éventuellement inclure un attribut `icon` fixé au nom de [l'une des icônes intégrées de Starlight](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts). - -```mdx -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> - -<CardGrid> - <Card title="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Moons" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> - -<CardGrid> - <Card title="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Moons" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -Utilisez une grille de cartes sur votre page d'accueil pour afficher les principales caractéristiques de votre projet. -Ajoutez l'attribut `stagger` pour décaler verticalement la deuxième colonne de cartes et ajouter un intérêt visuel : - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: diff --git a/docs/src/content/docs/fr-FR/guides/i18n.mdx b/docs/src/content/docs/fr-FR/guides/i18n.mdx deleted file mode 100644 index eb64d03f..00000000 --- a/docs/src/content/docs/fr-FR/guides/i18n.mdx +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Internationalisation (i18n) -description: Apprenez à configurer votre site Starlight pour qu'il prenne en charge plusieurs langues. ---- - -import FileTree from '../../../../components/file-tree.astro'; - -Starlight offre une prise en charge intégrée des sites multilingues, y compris le routage, le contenu de repli et la prise en charge complète des langues de droite à gauche (RTL). - -## Configurer i18n - -1. Indiquez à Starlight les langues que vous prenez en charge en passant `locales` et `defaultLocale` à l'intégration Starlight : - - ```js - // astro.config.mjs - import { defineConfig } from 'astro/config'; - import starlight from '@astrojs/starlight'; - - export default defineConfig({ - integrations: [ - starlight({ - title: 'My Docs', - // Définit l'anglais comme langue par défaut pour ce site. - defaultLocale: 'en', - locales: { - // Docs en anglais dans `src/content/docs/en/` - en: { - label: 'English', - }, - // Documentation en chinois simplifié dans `src/content/docs/zh/` - zh: { - label: '简体中文', - lang: 'zh-CN', - }, - // docs en arabe dans `src/content/docs/ar/` - ar: { - label: 'العربية', - dir: 'rtl', - }, - }, - }), - ], - }); - ``` - - Votre `defaultLocale` sera utilisé pour le contenu de repli et les étiquettes de l'interface utilisateur, donc choisissez la langue dans laquelle vous êtes le plus susceptible de commencer à écrire du contenu, ou pour laquelle vous avez déjà du contenu. - -2. Créez un répertoire pour chaque langue dans `src/content/docs/`. - Par exemple, pour la configuration montrée ci-dessus, créez les dossiers suivants : - - <FileTree> - - - src/ - - content/ - - docs/ - - ar/ - - en/ - - zh/ - - </FileTree> - -3. Vous pouvez maintenant ajouter des fichiers de contenu dans vos répertoires de langues. Utilisez le même nom de fichier pour associer les pages d'une langue à l'autre et profiter de l'ensemble des fonctionnalités i18n de Starlight, y compris le contenu de repli, les avis de traduction, etc. - - Par exemple, créez `ar/index.md` et `en/index.md` pour représenter la page d'accueil en arabe et en anglais respectivement. - -### Utiliser une racine locale - -Vous pouvez utiliser une racine locale pour servir une langue sans aucun préfixe i18n dans son chemin. Par exemple, si l'anglais est votre racine locale, le chemin d'une page en anglais ressemblera à `/about` au lieu de `/en/about`. - -Pour définir une racine locale, utilisez la clé `root` dans votre configuration `locales`. Si la racine locale est aussi la locale par défaut de votre contenu, supprimez `defaultLocale` ou donnez-lui la valeur `'root''. - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: 'My Docs', - defaultLocale: 'root', // optionnel - locales: { - root: { - label: 'English', - lang: 'en', // lang est nécessaire pour les locales de la racine - }, - zh: { - label: '简体中文', - lang: 'zh-CN', - }, - }, - }), - ], -}); -``` - -Lorsque vous utilisez une locale `root`, gardez les pages pour cette langue directement dans `src/content/docs/` au lieu d'un dossier dédié à la langue. Par exemple, voici les fichiers de la page d'accueil pour l'anglais et le chinois en utilisant la configuration ci-dessus : - -<FileTree> - -- src/ - - content/ - - docs/ - - **index.md** - - zh/ - - **index.md** - -</FileTree> - -#### Sites monolingues - -Par défaut, Starlight est un site monolingue (anglais). Pour créer un site monolingue dans une autre langue, définissez-la comme `root` dans votre configuration `locales` : - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: 'My Docs', - locales: { - root: { - label: '简体中文', - lang: 'zh-CN', - }, - }, - }), - ], -}); -``` - -Cela vous permet de remplacer la langue par défaut de Starlight sans activer d'autres fonctions d'internationalisation pour les sites multilingues, telles que le sélecteur de langue. - -## Contenu de remplacement - -Starlight s'attend à ce que vous créiez des pages équivalentes dans toutes vos langues. Par exemple, si vous avez un fichier `en/about.md`, créez un `about.md` pour chaque autre langue que vous supportez. Cela permet à Starlight de fournir un contenu de remplacement automatique pour les pages qui n'ont pas encore été traduites. - -Si une traduction n'est pas encore disponible pour une langue, Starlight affichera aux lecteurs le contenu de cette page dans la langue par défaut (définie via `defaultLocale`). Par exemple, si vous n'avez pas encore créé de version française de votre page À propos et que votre langue par défaut est l'anglais, les visiteurs de `/fr/about` verront le contenu anglais de `/en/about` avec un avis indiquant que cette page n'a pas encore été traduite. Cela vous permet d'ajouter du contenu dans votre langue par défaut et de le traduire progressivement lorsque vos traducteurs en ont le temps. - -## Traduire l'interface utilisateur de Starlight - -En plus d'héberger des fichiers de contenu traduits, Starlight vous permet de traduire les chaînes de l'interface utilisateur par défaut (par exemple, l'en-tête "Sur cette page" dans la table des matières) afin que vos lecteurs puissent découvrir votre site entièrement dans la langue sélectionnée. - -Les chaînes d'interface utilisateur traduites en anglais, allemand, japonais, portugais et espagnol sont fournies d'office, et nous acceptons les [contributions pour ajouter d'autres langues par défaut](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). - -Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collecte de données `i18n`. - -1. Configurez la collection de données `i18n` dans `src/content/config.ts` si elle n'est pas déjà configurée : - - ```js - // src/content/config.ts - import { defineCollection } from 'astro:content'; - import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; - - export const collections = { - docs: defineCollection({ schema: docsSchema() }), - i18n: defineCollection({ type: 'data', schema: i18nSchema() }), - }; - ``` - -2. Créez un fichier JSON dans `src/content/i18n/` pour chaque locale supplémentaire pour laquelle vous voulez fournir des chaînes de traduction pour l'interface utilisateur. - Par exemple, cela ajouterait des fichiers de traduction pour l'arabe et le chinois simplifié : - - <FileTree> - - - src/ - - content/ - - i18n/ - - ar.json - - zh-CN.json - - </FileTree> - -3. Ajoutez des traductions pour les clés que vous souhaitez traduire dans les fichiers JSON. Traduire uniquement les valeurs, en laissant les clés en anglais (e.g. `"search.label": "Buscar"`). - - Il s'agit des valeurs anglaises par défaut des chaînes de caractères existantes avec lesquelles Starlight est livré : - - ```json - { - "skipLink.label": "Aller au contenu", - "search.label": "rechercher", - "search.shortcutLabel": "(Presser / pour rechercher)", - "search.cancelLabel": "Annuler", - "themeSelect.accessibleLabel": "Selectionner le thème", - "themeSelect.dark": "Dark", - "themeSelect.light": "Light", - "themeSelect.auto": "Auto", - "languageSelect.accessibleLabel": "Selectionner la langue", - "menuButton.accessibleLabel": "Menu", - "sidebarNav.accessibleLabel": "Main", - "tableOfContents.onThisPage": "Sur cette page", - "tableOfContents.overview": "Vue d'ensemble", - "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", - "page.editLink": "Editer la page", - "page.lastUpdated": "Dernière mise à jour :", - "page.previousLink": "Suivant", - "page.nextLink": "Précédent" - } - ``` diff --git a/docs/src/content/docs/fr-FR/guides/project-structure.mdx b/docs/src/content/docs/fr-FR/guides/project-structure.mdx deleted file mode 100644 index 4ef16853..00000000 --- a/docs/src/content/docs/fr-FR/guides/project-structure.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Structure du projet -description: Apprenez à organiser les fichiers dans votre projet Starlight. ---- - -Ce guide vous montrera comment un projet Starlight est organisé et ce que font les différents fichiers de votre projet. - -Les projets Starlight suivent généralement la même structure de fichiers et de répertoires que les autres projets Astro. Voir [la documentation sur la structure des projets Astro](https://docs.astro.build/fr/core-concepts/project-structure/) pour plus de détails. - -## Fichiers et répertoires - -- `astro.config.mjs` — Le fichier de configuration d'Astro ; inclut l'intégration et la configuration de Starlight. -- `src/content/config.ts` — Fichier de configuration des collections de contenu ; ajoute les schémas de la matière première de Starlight à votre projet. -- `src/content/docs/` — Fichiers de contenu. Starlight transforme chaque fichier `.md`, `.mdx` ou `.mdoc` de ce répertoire en une page de votre site. -- `src/content/i18n/` (optionnel) — Données de traduction pour prendre en charge l'[internationalisation](/fr-FR/guides/i18n/). -- `src/` — Autre code source et fichiers (composants, styles, images, etc.) pour votre projet. -- `public/` — Actifs statiques (polices, favicon, PDFs, etc.) qui ne seront pas traités par Astro. - -## Exemple de contenu de projet - -Un répertoire de projet Starlight peut ressembler à ceci : - -import FileTree from '../../../../components/file-tree.astro'; - -<FileTree> - -- public/ - - favicon.svg -- src/ - - assets/ - - logo.svg - - screenshot.jpg - - components/ - - CustomButton.astro - - InteractiveWidget.jsx - - content/ - - docs/ - - guides/ - - 01-getting-started.md - - 02-advanced.md - - index.mdx - - config.ts - - env.d.ts -- astro.config.mjs -- package.json -- tsconfig.json - -</FileTree> diff --git a/docs/src/content/docs/fr-FR/index.mdx b/docs/src/content/docs/fr-FR/index.mdx deleted file mode 100644 index 1bdcaac5..00000000 --- a/docs/src/content/docs/fr-FR/index.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Starlight 🌟 Construire des sites de documentation avec Astro -description: Starlight vous aide à créer de magnifiques sites web de documentation très performants avec Astro. -template: splash -hero: - title: Faites briller vos documents avec Starlight - tagline: Tout ce dont vous avez besoin pour créer un excellent site web de documentation. Rapide, accessible et facile à utiliser. - image: - file: ../../../assets/hero-star.webp - actions: - - text: Mise en route - icon: right-arrow - variant: primary - link: /fr-FR/getting-started/ - - text: Voir sur GitHub - icon: external - link: https://github.com/withastro/starlight ---- - -import { CardGrid, Card } from '@astrojs/starlight/components'; -import AboutAstro from '../../../components/about-astro.astro'; - -<CardGrid stagger> - <Card title="Une documentation qui enchante" icon="open-book"> - Comprend : Navigation dans le site, recherche, internationalisation, référencement naturel, typographie facile à lire, mise en évidence du code, mode sombre, etc. - </Card> - <Card title="Propulsé par Astro" icon="rocket"> - Exploitez toute la puissance et les performances d'Astro. Étendez Starlight avec vos intégrations et bibliothèques Astro préférées. - </Card> - <Card title="Markdown, Markdoc, et MDX" icon="document"> - Apportez votre langage de balisage préféré. Starlight vous offre une validation frontmatter intégrée avec la sécurité de type TypeScript. - </Card> - <Card title="Apportez vos propres composants d'interface utilisateur" icon="puzzle"> - Starlight est une solution de documentation complète, indépendante du cadre de travail. Étendez avec React, Vue, Svelte, Solid, et plus encore. - </Card> -</CardGrid> - -<AboutAstro title="Présenté par"> -Astro est le framework web tout-en-un conçu pour la vitesse. -Tirez votre contenu de n'importe où et déployez-le partout, le tout alimenté par vos composants et bibliothèques d'interface utilisateur préférés. - -[En savoir plus sur Astro](https://astro.build/) - -</AboutAstro> diff --git a/docs/src/content/docs/fr-FR/reference/configuration.md b/docs/src/content/docs/fr-FR/reference/configuration.md deleted file mode 100644 index 4e6ab2f9..00000000 --- a/docs/src/content/docs/fr-FR/reference/configuration.md +++ /dev/null @@ -1,326 +0,0 @@ ---- -title: Référence de configuration -description: Une vue d'ensemble de toutes les options de configuration prises en charge par Starlight. ---- - -## Configuration de l'intégration `starlight` - -Starlight est une intégration construite sur le framework web [Astro](https://astro.build). Vous pouvez configurer votre projet dans le fichier de configuration Astro `astro.config.mjs` : - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: "Mon délicieux site de docs", - }), - ], -}); -``` - -Vous pouvez passer les options suivantes à l'intégration `starlight`. - -### `title` (obligatoire) - -**type:** `string` - -Définissez le titre de votre site web. Il sera utilisé dans les métadonnées et dans le titre de l'onglet du navigateur. - -### `description` - -**type:** `string` - -Définissez la description de votre site web. Utilisée dans les métadonnées partagées avec les moteurs de recherche dans la balise `<meta name="description">` si `description` n'est pas définie dans le frontmatter d'une page. - -### `logo` - -**type:** [`LogoConfig`](#logoconfig) - -Définit une image de logo à afficher dans la barre de navigation à côté ou à la place du titre du site. Vous pouvez soit définir une seule propriété `src`, soit définir des sources d'images séparées pour `light` et `dark`. - -```js -starlight({ - logo: { - src: '/src/assets/my-logo.svg', - }, -}); -``` - -#### `LogoConfig` - -```ts -type LogoConfig = { alt?: string; replacesTitle?: boolean } & ( - | { src: string } - | { light: string; dark: string } -); -``` - -### `tableOfContents` - -**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` -**default:** `{ minHeadingLevel: 2; maxHeadingLevel: 3; }` - -Configurez la table des matières affichée à droite de chaque page. Par défaut, les titres `<h2>` et `<h3>` seront inclus dans cette table des matières. - -### `editLink` - -**type:** `{ baseUrl: string }` - -Permet d'activer les liens "Modifier cette page" en définissant l'URL de base qu'ils doivent utiliser. Le lien final sera `editLink.baseUrl` + le chemin de la page actuelle. Par exemple, pour permettre l'édition de pages dans le repo `withastro/starlight` sur GitHub : - -```js -starlight({ - editLink: { - baseUrl: 'https://github.com/withastro/starlight/edit/main/', - }, -}); -``` - -Avec cette configuration, une page `/introduction` aurait un lien d'édition pointant vers `https://github.com/withastro/starlight/edit/main/src/docs/introduction.md`. - -### `sidebar` - -**type:** [`SidebarGroup[]`](#sidebargroup) - -Configure les éléments de navigation de la barre latérale de votre site. - -Une barre latérale est un tableau de groupes, chacun avec un `label` pour le groupe et un tableau `items` ou un objet de configuration `autogenerate`. - -Vous pouvez définir manuellement le contenu d'un groupe en utilisant `items`, qui est un tableau pouvant inclure des liens et des sous-groupes. Vous pouvez aussi générer automatiquement le contenu d'un groupe à partir d'un répertoire spécifique de votre documentation, en utilisant `autogenerate`. - -```js -starlight({ - sidebar: [ - // Un groupe intitulé "Commencer ici" contenant deux liens. - { - label: 'Commencer ici', - items: [ - { label: 'Introduction', link: '/intro' }, - { label: 'Etapes', link: '/next-steps' }, - ], - }, - // Un groupe qui renvoie à toutes les pages du répertoire de référence. - { - label: 'Référence', - autogenerate: { directory: 'reference' }, - }, - ], -}); -``` - -#### Tri - -Les groupes de barres latérales générées automatiquement sont triés par nom de fichier et par ordre alphabétique. -Par exemple, une page générée à partir de `astro.md` apparaîtrait au-dessus de la page de `starlight.md`. - -#### Traduire les étiquettes - -Si votre site est multilingue, le `label` de chaque élément est considéré comme étant dans la locale par défaut. Vous pouvez définir une propriété `translations` pour fournir des étiquettes pour les autres langues supportées : - -```js -sidebar: [ - // Un exemple de barre latérale avec des étiquettes traduites en anglais. - { - label: 'Commencer ici', - translations: { en: 'Start here' }, - items: [ - { - label: 'Bien démarrer', - translations: { en: 'Getting Started' }, - link: '/getting-started', - }, - { - label: 'Structure du projet', - translations: { en: 'Project Structure' }, - link: '/structure', - }, - ], - }, -]; -``` - -#### `SidebarGroup` - -```ts -type SidebarGroup = - | { - label: string; - translations?: Record<string, string>; - items: Array<LinkItem | SidebarGroup>; - } - | { - label: string; - translations?: Record<string, string>; - autogenerate: { - directory: string; - }; - }; -``` - -#### `LinkItem` - -```ts -interface LinkItem { - label: string; - link: string; -} -``` - -### `locales` - -**type:** `{ [dir: string]: LocaleConfig }` - -Configurez l'internationalisation (i18n) de votre site en définissant les `locales` supportées. - -Chaque entrée doit utiliser comme clé le répertoire dans lequel les fichiers de cette langue sont sauvegardés. - -```js -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import starlight from '@astrojs/starlight'; - -export default defineConfig({ - integrations: [ - starlight({ - title: 'My Site', - // Définit l'anglais comme langue par défaut pour ce site. - defaultLocale: 'en', - locales: { - // Documentations en anglais danse trouve dans `src/content/docs/en/` - en: { - label: 'English', - }, - // Documentations en Chinois simplifié se trouve dans `src/content/docs/zh/` - zh: { - label: '简体中文', - lang: 'zh-CN', - }, - // Documentations en Arabe se trouve dans `src/content/docs/ar/` - ar: { - label: 'العربية', - dir: 'rtl', - }, - }, - }), - ], -}); -``` - -#### Options des paramètres linguistiques - -Vous pouvez définir les options suivantes pour chaque locale : - -##### `label` (obligatoire) - -**type:** `string` - -L'étiquette de cette langue à afficher aux utilisateurs, par exemple dans le sélecteur de langue. Le plus souvent, il s'agit du nom de la langue tel qu'un utilisateur de cette langue s'attendrait à le lire, par exemple `"English"`, `"العربية"`, ou `"简体中文"`. - -##### `lang` - -**type:** `string` - -La balise BCP-47 pour cette langue, par exemple `"en"`, `"ar"`, ou `"zh-CN"`. S'il n'est pas défini, le nom du répertoire de la langue sera utilisé par défaut. - -##### `dir` - -**type:** `'ltr' | 'rtl'` - -Le sens d'écriture de cette langue ; `"ltr"` pour gauche à droite (par défaut) ou `"rtl"` pour droite à gauche. - -#### Locale racine - -Vous pouvez servir la langue par défaut sans répertoire `/lang/` en définissant une locale `root` : - -```js -starlight({ - locales: { - root: { - label: 'English', - lang: 'en', - }, - fr: { - label: 'Français', - }, - }, -}); -``` - -Par exemple, cela vous permet de servir `/getting-started/` comme une route anglaise et d'utiliser `/fr/getting-started/` comme la page française équivalente. - -### `defaultLocale` - -**type:** `string` - -Définit la langue par défaut pour ce site. -La valeur doit correspondre à l'une des clés de votre objet [`locales`](#locales). -(Si votre langue par défaut est votre [root locale](#root-locale), vous pouvez sauter cette étape). - -La locale par défaut sera utilisée pour fournir un contenu de remplacement lorsque les traductions sont manquantes. - -### `social` - -**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }` - -Détails optionnels sur les comptes de médias sociaux pour ce site. L'ajout de l'un d'entre eux les affichera sous forme de liens iconiques dans l'en-tête du site. - -```js -starlight({ - social: { - discord: 'https://astro.build/chat', - github: 'https://github.com/withastro/starlight', - mastodon: 'https://m.webtoo.ls/@astro', - twitter: 'https://twitter.com/astrodotbuild', - }, -}); -``` - -### `customCss` - -**type:** `string[]` - -Fournit des fichiers CSS pour personnaliser l'aspect et la convivialité de votre site Starlight. - -Prend en charge les fichiers CSS locaux relatifs à la racine de votre projet, par exemple `'/src/custom.css'`, et les CSS que vous avez installés en tant que module npm, par exemple `'@fontsource/roboto'`. - -```js -starlight({ - customCss: ['/src/custom-styles.css', '@fontsource/roboto'], -}); -``` - -### `head` - -**type:** [`HeadConfig[]`](#headconfig) - -Ajoute des balises personnalisées au `<head>` de votre site Starlight. -Cela peut être utile pour ajouter des analyses et d'autres scripts et ressources tiers. - -```js -starlight({ - head: [ - // Exemple : ajouter un script d'analyse Fathom tag. - { - tag: 'script', - attrs: { - src: 'https://cdn.usefathom.com/script.js', - 'data-site': 'MY-FATHOM-ID', - defer: true, - }, - }, - ], -}); -``` - -#### `HeadConfig` - -```ts -interface HeadConfig { - tag: string; - attrs?: Record<string, string | boolean | undefined>; - content?: string; -} -``` diff --git a/docs/src/content/docs/fr-FR/reference/frontmatter.md b/docs/src/content/docs/fr-FR/reference/frontmatter.md deleted file mode 100644 index cdff1481..00000000 --- a/docs/src/content/docs/fr-FR/reference/frontmatter.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Frontmatter Reference -description: Une vue d'ensemble des champs frontmatter par défaut pris en charge par Starlight. ---- - -Vous pouvez personnaliser des pages Markdown et MDX individuelles dans Starlight en définissant des valeurs dans leur page de garde. Par exemple, une page normale peut définir les champs `title` et `description` : - -```md ---- -title: A propos de ce projet -description: En savoir plus sur le projet sur lequel je travaille. ---- - -Bienvenue sur la page "à propos" ! -``` - -## Champs de la page d'accueil - -### `title` (obligatoire) - -**type:** `string` - -Vous devez fournir un titre pour chaque page. Il sera affiché en haut de la page, dans les onglets du navigateur et dans les métadonnées de la page. - -### `description` - -**type:** `string` - -La description de la page est utilisée pour les métadonnées de la page et sera reprise par les moteurs de recherche et dans les aperçus des médias sociaux. - -### `editUrl` - -**type:** `string | boolean` - -Remplace la [configuration globale `editLink`](/fr-FR/reference/configuration/#editlink). Mettez `false` pour désactiver le lien "Editer la page" pour une page spécifique ou pour fournir une URL alternative où le contenu de cette page est éditable. - -### `head` - -**type:** [`HeadConfig[]`](/fr-FR/reference/configuration/#headconfig) - -Vous pouvez ajouter des balises supplémentaires au champ `<head>` de votre page en utilisant le champ `head` frontmatter. Cela signifie que vous pouvez ajouter des styles personnalisés, des métadonnées ou d'autres balises à une seule page. Similaire à [l'option globale `head`](/fr-FR/reference/configuration/#head). - -```md ---- -title: A propos de nous -head: - # Utiliser une balise <title> personnalisée - - tag: title - content: Titre personnalisé à propos de nous ---- -``` - -### `tableOfContents` - -**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` - -Remplace la [configuration globale `tableOfContents`](/fr-FR/reference/configuration/#tableofcontents). -Personnalisez les niveaux d'en-tête à inclure ou mettez `false` pour cacher la table des matières sur cette page. - -### `template` - -**type:** `'doc' | 'splash'` -**default:** `'doc'` - -Définit le modèle de mise en page pour cette page. -Les pages utilisent la mise en page `'doc'`' par défaut. -La valeur `'splash''` permet d'utiliser une mise en page plus large, sans barres latérales, conçue pour les pages d'atterrissage. - -### `hero` - -**type:** [`HeroConfig`](#heroconfig) - -Ajoute un composant héros en haut de la page. Fonctionne bien avec `template : splash`. - -Par exemple, cette configuration montre quelques options communes, y compris le chargement d'une image depuis votre dépôt. - -```md ---- -title: Ma page d'accueil -template: splash -hero: - title: 'Mon projet : Stellar Stuffer Sooner' - tagline: Emmenez vos affaires sur la lune et revenez-y en un clin d'œil. - image: - alt: Un logo aux couleurs vives et scintillantes - file: ../../assets/logo.png - actions: - - text: En savoir plus - link: /getting-started/ - icon: right-arrow - variant: primary - - text: Voir sur GitHub - link: https://github.com/astronaut/my-project - icon: external ---- -``` - -#### `HeroConfig` - -```ts -interface HeroConfig { - title?: string; - tagline?: string; - image?: { - alt?: string; - // Chemin relatif vers une image dans votre référentiel. - file?: string; - // HTML brut à utiliser dans l'emplacement de l'image. - // Il peut s'agir d'une balise `<img>` personnalisée ou d'une balise `<svg>` en ligne. - html?: string; - }; - actions?: Array<{ - text: string; - link: string; - variant: 'primary' | 'secondary' | 'minimal'; - icon: string; - }>; -} -``` diff --git a/docs/src/content/docs/fr/environmental-impact.md b/docs/src/content/docs/fr/environmental-impact.md new file mode 100644 index 00000000..f9c8c919 --- /dev/null +++ b/docs/src/content/docs/fr/environmental-impact.md @@ -0,0 +1,135 @@ +--- +title: Documents écologiques +description: Découvrez comment Starlight peut vous aider à créer des sites de documentation plus écologiques et à réduire votre empreinte carbone. +--- + +Les estimations de l'impact climatique de l'industrie du web varient entre [2 %][sf] et [4 % des émissions mondiales de carbone][bbc], ce qui équivaut à peu près aux émissions de l'industrie du transport aérien. +Le calcul de l'impact écologique d'un site web repose sur de nombreux facteurs complexes, mais ce guide contient quelques conseils pour réduire l'empreinte écologique de votre site documentaire. + +La bonne nouvelle, c'est que le choix de Starlight est un excellent début. +Selon le Website Carbon Calculator, ce site est [plus propre que 99 % des pages web testées][sl-carbon], produisant 0,01 g de CO₂ par page visitée. + +## Poids de la page + +Plus une page web transfère de données, plus elle nécessite de ressources énergétiques. +En avril 2023, la page web médiane demandait à l'utilisateur de télécharger plus de 2 000 Ko selon les [données de l'archive HTTP][http]. + +Starlight construit des pages aussi légères que possible. +Par exemple, lors de sa première visite, un utilisateur téléchargera moins de 50 Ko de données compressées, soit seulement 2,5 % de la médiane des archives HTTP. +Avec une bonne stratégie de mise en cache, les navigations suivantes peuvent télécharger jusqu'à 10 Ko. + +### Images + +Bien que Starlight fournisse une bonne base de référence, les images que vous ajoutez à vos pages de documentation peuvent rapidement augmenter le poids de vos pages. +Starlight utilise le [support d'actifs optimisés][assets] d'Astro pour optimiser les images locales dans vos fichiers Markdown et MDX. + +### Composants d'interface utilisateur + +Les composants construits avec des frameworks d'interface utilisateur tels que React ou Vue peuvent facilement ajouter de grandes quantités de JavaScript à une page. +Starlight étant construit sur Astro, les composants de ce type chargent **zéro JavaScript côté client par défaut** grâce à [Astro Islands][islands]. + +### Mise en cache + +La mise en cache est utilisée pour contrôler la durée pendant laquelle un navigateur stocke et réutilise les données qu'il a déjà téléchargées. +Une bonne stratégie de mise en cache permet à l'utilisateur d'obtenir un nouveau contenu dès qu'il est modifié, tout en évitant de télécharger inutilement le même contenu à plusieurs reprises lorsqu'il n'a pas changé. + +La façon la plus courante de configurer la mise en cache est d'utiliser l'en-tête HTTP [`Cache-Control`][cache]. +Lorsque vous utilisez Starlight, vous pouvez définir une longue durée de mise en cache pour tout ce qui se trouve dans le répertoire `/_astro/`. +Ce répertoire contient des fichiers CSS, JavaScript, et d'autres actifs intégrés qui peuvent être mis en cache pour toujours, réduisant ainsi les téléchargements inutiles : + +``` +Cache-Control: public, max-age=604800, immutable +``` + +La configuration de la mise en cache dépend de votre hébergeur. Par exemple, Vercel applique cette stratégie de mise en cache pour vous sans configuration nécessaire, tandis que vous pouvez définir des [en-têtes personnalisés pour Netlify][ntl-headers] en ajoutant un fichier `public/_headers` à votre projet : + +``` +/_astro/* + Cache-Control: public + Cache-Control: max-age=604800 + Cache-Control: immutable +``` + +[cache]: https://csswizardry.com/2019/03/cache-control-for-civilians/ +[ntl-headers]: https://docs.netlify.com/routing/headers/ + +## Consommation d'énergie + +La façon dont une page web est construite peut avoir un impact sur la puissance nécessaire pour fonctionner sur l'appareil d'un utilisateur. +En utilisant un minimum de JavaScript, Starlight réduit la puissance de traitement dont le téléphone, la tablette ou l'ordinateur d'un utilisateur a besoin pour charger et afficher les pages. + +Soyez vigilant lorsque vous ajoutez des fonctionnalités telles que des scripts de suivi analytique ou des contenus à forte teneur en JavaScript, comme des vidéos intégrées, car ils peuvent augmenter la consommation d'énergie de la page. +Si vous avez besoin d'analyses, envisagez de choisir une option légère comme [Cabin][cabin], [Fathom][fathom], ou [Plausible][plausible]. +Les vidéos intégrées comme celles de YouTube et de Vimeo peuvent être améliorées en attendant de [charger la vidéo lors de l'interaction avec l'utilisateur][lazy-video]. +Des paquets comme [`astro-embed`][embed] peuvent aider pour les services communs. + +:::tip[Le saviez-vous ?] +L'analyse et la compilation de JavaScript est l'une des tâches les plus coûteuses pour les navigateurs. +Par rapport au rendu d'une image JPEG de même taille, [le traitement de JavaScript peut prendre plus de 30 fois plus de temps][coût-de-js]. +::: + +[cabin]: https://withcabin.com/ +[fathom]: https://usefathom.com/ +[plausible]: https://plausible.io/ +[lazy-video]: https://web.dev/iframe-lazy-loading/ +[embed]: https://www.npmjs.com/package/astro-embed +[cost-of-js]: https://medium.com/dev-channel/the-cost-of-javascript-84009f51e99e + +## Hébergement + +Le lieu d'hébergement d'une page web peut avoir un impact important sur le degré de respect de l'environnement de votre site de documentation. +Les centres de données et les fermes de serveurs peuvent avoir un impact écologique important, notamment en raison de leur consommation élevée d'électricité et de leur utilisation intensive de l'eau. + +Le choix d'un hébergeur utilisant des énergies renouvelables se traduira par une réduction des émissions de carbone pour votre site. Le [Green Web Directory][gwb] est un outil qui peut vous aider à trouver des hébergeurs. + +[gwb]: https://www.thegreenwebfoundation.org/directory/ + +## Comparaisons + +Curieux de savoir comment les autres frameworks de documentation se comparent ? +Ces tests avec le [Website Carbon Calculator][wcc] comparent des pages similaires construites avec différents outils. + +| Framework | CO₂ par page visitée | +| --------------------------- | ------------------ | +| [Starlight][sl-carbon] | 0.01g | +| [VitePress][vp-carbon] | 0.05g | +| [Sphinx][sx-carbon] | 0.07g | +| [MkDocs][mk-carbon] | 0.10g | +| [Nextra][nx-carbon] | 0.11g | +| [Docusaurus][ds-carbon] | 0.24g | +| [Read the Docs][rtd-carbon] | 0.24g | +| [GitBook][gb-carbon] | 0.71g | + +<small>Données collectées le 14 mai 2023. Cliquez sur un lien pour voir les chiffres actualisés.</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/ +[sx-carbon]: https://www.websitecarbon.com/website/sphinx-doc-org-en-master-usage-quickstart-html/ +[mk-carbon]: https://www.websitecarbon.com/website/mkdocs-org-getting-started/ +[nx-carbon]: https://www.websitecarbon.com/website/nextra-site-docs-docs-theme-start/ +[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/ + +## Plus de ressources + +### Outils + +- [Website Carbon Calculator][wcc] +- [Ecograder](https://ecograder.com/) +- [WebPageTest Carbon Control](https://www.webpagetest.org/carbon-control/) +- [Ecoping](https://ecoping.earth/) + +### Articles et discussions + +- [“Building a greener web”](https://youtu.be/EfPoOt7T5lg), conférence de Michelle Barker +- [“Sustainable Web Development Strategies Within An Organization”](https://www.smashingmagazine.com/2022/10/sustainable-web-development-strategies-organization/), article par Michelle Barker +- [“A sustainable web for everyone”](https://2021.stateofthebrowser.com/speakers/tom-greenwood/), conférence de Tom Greenwood +- [“How Web Content Can Affect Power Usage”](https://webkit.org/blog/8970/how-web-content-can-affect-power-usage/), article de Benjamin Poulain et Simon Fraser + +[sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/ +[bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think +[http]: https://httparchive.org/reports/state-of-the-web +[assets]: https://docs.astro.build/en/guides/assets/ +[islands]: https://docs.astro.build/en/concepts/islands/ +[wcc]: https://www.websitecarbon.com/ diff --git a/docs/src/content/docs/fr/getting-started.mdx b/docs/src/content/docs/fr/getting-started.mdx new file mode 100644 index 00000000..a9ab610b --- /dev/null +++ b/docs/src/content/docs/fr/getting-started.mdx @@ -0,0 +1,86 @@ +--- +title: Mise en route +description: Apprenez à créer votre prochain site de documentation avec Starlight by Astro. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +:::caution[Work in progress] +Starlight est en début de développement. +Si vous trouvez quelque chose qui ne fonctionne pas, [ouvrez une issue sur GitHub](https://github.com/withastro/starlight/issues/new/choose) ou faites-le nous savoir sur [Discord](https://astro.build/chat). +::: + +## Créer un nouveau projet + +Starlight est un thème de documentation complet construit sur le framework [Astro](https://astro.build). + +Vous pouvez créer un nouveau projet Astro + Starlight en utilisant la commande suivante : + +<Tabs> +<TabItem label="npm"> + +```sh +# créer un nouveau projet avec npm +npm create astro@latest -- --template starlight +``` + +</TabItem> +<TabItem label="pnpm"> + +```sh +# créer un nouveau projet avec pnpm +pnpm create astro --template starlight +``` + +</TabItem> +<TabItem label="Yarn"> + +```sh +# créer un nouveau projet avec yarn +yarn create astro --template starlight +``` + +</TabItem> +</Tabs> + +Cela créera un nouveau [répertoire de projet](/fr/guides/projet-structure/) avec tous les fichiers et configurations nécessaires pour votre site. + +:::tip[Voir en action] +Essayez Starlight dans votre navigateur : +[ouvrir le modèle sur StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics). +::: + +## Créer du contenu avec Starlight + +Starlight est prêt pour que vous puissiez ajouter du nouveau contenu, ou apporter vos fichiers existants ! + +### Formats de fichiers + +Starlight prend en charge la création de contenu en Markdown et MDX. (Vous pouvez ajouter la prise en charge de Markdoc en installant l'intégration expérimentale [Astro Markdoc integration](https://docs.astro.build/fr/guides/integrations-guide/markdoc/).) + +### Ajouter des pages +Ajoutez automatiquement de nouvelles pages à votre site en créant des fichiers `.md` ou `.mdx` dans `src/content/docs/`. Ajoutez des sous-dossiers pour organiser vos fichiers, et pour créer plusieurs segments de chemin : + +```js +`src/content/docs/hello-world.md` -> `votre-site/hello-world` +`src/content/docs/guides/faq.md` -> `votre-site/guides/faq` +``` + +### Type-safe frontmatter + +Toutes les pages Starlight partagent un [ensemble commun de propriétés de présentation](/fr/reference/frontmatter/) personnalisable pour contrôler l'apparence de la page : + +```md +--- +title: Bonjour, le monde ! +description: Ceci est une page de mon site web propulsé par Starlight. +--- +``` + +Si vous oubliez quelque chose d'important, Starlight vous le fera savoir. + +## Déployer votre site web Starlight + +Une fois que vous avez créé et personnalisé votre site Web Starlight, vous pouvez le déployer sur un serveur Web ou une plateforme d'hébergement de votre choix, y compris Netlify, Vercel, GitHub Pages et bien d'autres. + +[Pour en savoir plus sur le déploiement d'un site Astro, consultez la documentation Astro](https://docs.astro.build/fr/guides/deploy/) diff --git a/docs/src/content/docs/fr/guides/authoring-content.md b/docs/src/content/docs/fr/guides/authoring-content.md new file mode 100644 index 00000000..4a062b93 --- /dev/null +++ b/docs/src/content/docs/fr/guides/authoring-content.md @@ -0,0 +1,209 @@ +--- +title: Création de contenu en Markdown +description: Un aperçu de la syntaxe Markdown prise en charge par Starlight. +--- + +Starlight prend en charge l'ensemble de la syntaxe [Markdown](https://daringfireball.net/projects/markdown/) dans les fichiers `.md` ainsi que la syntaxe frontale [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) pour définir des métadonnées telles qu'un titre et une description. + +Veillez à consulter les [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) ou les [Markdoc docs](https://markdoc.dev/docs/syntax) si vous utilisez ces formats de fichiers, car la prise en charge et l'utilisation de Markdown peuvent varier. + +## Styles en ligne + +Le texte peut être **gras**, _italique_, ou ~~barré~~. + +```md +Le texte peut être **gras**, _italique_, ou ~~barré~~. +``` + +Vous pouvez [faire un lien vers une autre page](/fr/getting-started/). + +```md +Vous pouvez [faire un lien vers une autre page](/fr/getting-started/). +``` + +Vous pouvez mettre en évidence le `code en ligne` à l'aide d'un astérisque. + +```md +Vous pouvez mettre en évidence le `code en ligne` à l'aide de barres de défilement. +``` + +## Images + +Les images dans Starlight utilisent la prise en charge intégrée des ressources optimisées d'Astro. + +Markdown et MDX supportent la syntaxe Markdown pour l'affichage des images qui inclut le texte alt pour les lecteurs d'écran et les technologies d'assistance. + +![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) + +```md +![Une illustration de planètes et d'étoiles avec le mot "astro"](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) +``` + +Les chemins d'accès relatifs aux images sont également supportés pour les images stockées localement dans votre projet. + +```md +// src/content/docs/page-1.md + +![Une fusée dans l'espace.](../../assets/images/rocket.svg) +``` + +## En-têtes + +Vous pouvez structurer le contenu à l'aide d'un titre. En Markdown, les titres sont indiqués par un nombre de `#` en début de ligne. + +### Comment structurer le contenu d'une page dans Starlight + +Starlight est configuré pour utiliser automatiquement le titre de votre page comme titre de premier niveau et inclura un titre "Aperçu" en haut de la table des matières de chaque page. Nous vous recommandons de commencer chaque page par un paragraphe de texte normal et d'utiliser des titres de page à partir de `<h2>` : + +```md +--- +title: Guide Markdown +description: Comment utiliser Markdown dans Starlight +--- + +Cette page décrit comment utiliser Markdown dans Starlight. + +## Styles en ligne + +## Titres + +``` + +### Liens d'ancrage automatiques pour les titres + +L'utilisation de titres en Markdown vous donnera automatiquement des liens d'ancrage afin que vous puissiez accéder directement à certaines sections de votre page : + +```md +--- +title: Ma page de contenu +description: Comment utiliser les liens d'ancrage intégrés de Starlight +--- +## Introduction + +Je peux faire un lien vers [ma conclusion](#conclusion) plus bas sur la même page. + +## Conclusion + +`https://my-site.com/page1/#introduction` renvoie directement à mon Introduction. +``` + +Les titres de niveau 2 (`<h2>`) et de niveau 3 (`<h3>`) apparaissent automatiquement dans la table des matières de la page. + +## Asides + +Les Asides (également connus sous le nom de "callouts") sont utiles pour afficher des informations secondaires à côté du contenu principal d'une page. + +Starlight fournit une syntaxe Markdown personnalisée pour le rendu des apartés. Les blocs d'apartés sont indiqués en utilisant une paire de triples points `:::` pour envelopper votre contenu, et peuvent être de type `note`, `tip`, `caution` ou `danger`. + +Vous pouvez imbriquer n'importe quel autre type de contenu Markdown à l'intérieur d'un aparté, mais les aparté sont mieux adaptés à des morceaux de contenu courts et concis. + +### Note aside + +:::note +Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : + +```sh +npm run create astro@latest --template starlight +``` + +::: + +````md +:::note +Starlight est une boîte à outils pour sites web de documentation construite avec [Astro](https://astro.build/). Vous pouvez démarrer avec cette commande : + +```sh +npm run create astro@latest --template starlight +``` + +::: +```` + +### Titres personnalisés dans les asides + +Vous pouvez spécifier un titre personnalisé pour l'aparté entre crochets après le type d'aparté, par exemple `:::tip[Le saviez-vous ?]`. + +:::tip[Le saviez-vous ?] +Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). +::: + +```md +:::tip[Le saviez-vous ?] +Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Architecture"](https://docs.astro.build/fr/concepts/islands/). +::: +``` + +### Plus de types pour l'aside + +Les apartés de type Attention et Danger sont utiles pour attirer l'attention de l'utilisateur sur des détails qui pourraient le faire trébucher. +Si vous les utilisez souvent, c'est peut-être aussi le signe que la chose que vous documentez gagnerait à être repensée. + +:::caution +Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). +::: + +:::danger +Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. + +- Navigation claire +- Thème de couleurs configurable par l'utilisateur +- [Support i18n](/fr/guides/i18n) + +::: + +```md +:::caution +Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). +::: + +:::danger +Vos utilisateurs peuvent être plus productifs et trouver votre produit plus facile à utiliser grâce aux fonctionnalités utiles de Starlight. + +- Navigation claire +- Thème de couleurs configurable par l'utilisateur +- [Support i18n](/fr/guides/i18n) + +::: +``` + +## Blockquotes + +> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. +> +> Les guillemets sont indiqués par un `>` au début de chaque ligne. + +```md +> Il s'agit d'une citation en bloc, couramment utilisée pour citer une autre personne ou un document. +> +> Les guillemets sont indiqués par un `>` au début de chaque ligne. +``` + +## Code blocks + +Un bloc de code est indiqué par un bloc avec trois crochets <code>```</code> au début et à la fin. Vous pouvez indiquer le langage de programmation utilisé après les premiers crochets. + +```js +// Code Javascript avec mise en évidence de la syntaxe. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` + +````md +```js +// Code Javascript avec mise en évidence de la syntaxe. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` +```` + +```md +Les longs blocs de code d'une seule ligne ne doivent pas être enveloppés. Ils doivent défiler horizontalement s'ils sont trop longs. Cette ligne devrait être suffisamment longue pour le démontrer. +``` + +## Autres fonctionnalités courantes de Markdown + +Starlight prend en charge toutes les autres syntaxes de rédaction Markdown, telles que les listes et les tableaux. Voir [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) pour un aperçu rapide de tous les éléments de la syntaxe Markdown. diff --git a/docs/src/content/docs/fr/guides/components.mdx b/docs/src/content/docs/fr/guides/components.mdx new file mode 100644 index 00000000..5e1000cf --- /dev/null +++ b/docs/src/content/docs/fr/guides/components.mdx @@ -0,0 +1,111 @@ +--- +title: Composants +description: Utilisation de composants dans MDX avec Starlight. +--- + +Les composants vous permettent de réutiliser facilement un élément d'interface utilisateur ou de style de manière cohérente. +Il peut s'agir par exemple d'une carte de lien ou d'une intégration YouTube. +Starlight prend en charge l'utilisation de composants dans les fichiers [MDX](https://mdxjs.com/) et fournit des composants courants que vous pouvez utiliser. + +[Pour en savoir plus sur la création de composants, consultez les Astro Docs](https://docs.astro.build/fr/core-concepts/astro-components/). + +## Utilisation d'un composant + +Vous pouvez utiliser un composant en l'important dans votre fichier MDX et en le rendant sous forme de balise JSX. +Ces balises ressemblent à des balises HTML mais commencent par une lettre majuscule correspondant au nom de votre déclaration `import` : + +```mdx +--- +# src/content/docs/index.mdx +title: Bienvenue dans ma documentation +--- + +import SomeComponent from '../../components/SomeComponent.astro'; +import AnotherComponent from '../../components/AnotherComponent.astro'; + +<SomeComponent prop="something" /> + +<AnotherComponent> + Les composants peuvent également contenir du **contenu imbriqué**. +</AnotherComponent> +``` + +Starlight étant alimenté par Astro, vous pouvez ajouter la prise en charge des composants construits avec n'importe quel [cadre d'interface utilisateur pris en charge (React, Preact, Svelte, Vue, Solid, Lit et Alpine)](https://docs.astro.build/fr/core-concepts/framework-components/) dans vos fichiers MDX. +Pour en savoir plus sur [l'utilisation de composants dans MDX](https://docs.astro.build/fr/guides/markdown-content/#using-components-in-mdx), consultez la documentation Astro. + +## Composants intégrés + +Starlight fournit quelques composants intégrés pour les cas d'utilisation courants de la documentation. +Ces composants sont disponibles dans le paquet `@astrojs/starlight/components`. + +### Onglets + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Vous pouvez afficher une interface à onglets en utilisant les composants `<Tabs>` et `<TabItem>`. +Chaque `<TabItem>` doit avoir un `label` à afficher aux utilisateurs. + +```mdx +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +<Tabs> + <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> + <TabItem label="Moons">Io, Europa, Ganymede</TabItem> +</Tabs> +``` + +Le code ci-dessus génère les onglets suivants sur la page : + +<Tabs> + <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> + <TabItem label="Moons">Io, Europa, Ganymede</TabItem> +</Tabs> + +### Cards + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +Vous pouvez afficher du contenu dans une boîte correspondant aux styles de Starlight en utilisant le composant `<Card>`. +Enveloppez plusieurs cartes dans le composant `<CardGrid>` pour afficher les cartes côte à côte lorsqu'il y a suffisamment d'espace. + +Une `<Card>` nécessite un `titre` et peut éventuellement inclure un attribut `icon` fixé au nom de [l'une des icônes intégrées de Starlight](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts). + +```mdx +import { Card, CardGrid } from '@astrojs/starlight/components'; + +<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> + +<CardGrid> + <Card title="Stars" icon="star"> + Sirius, Vega, Betelgeuse + </Card> + <Card title="Moons" icon="moon"> + Io, Europa, Ganymede + </Card> +</CardGrid> +``` + +Le code ci-dessus génère ce qui suit sur la page : + +<Card title="Check this out">Contenu intéressant que vous souhaitez mettre en évidence.</Card> + +<CardGrid> + <Card title="Stars" icon="star"> + Sirius, Vega, Betelgeuse + </Card> + <Card title="Moons" icon="moon"> + Io, Europa, Ganymede + </Card> +</CardGrid> + +:::tip +Utilisez une grille de cartes sur votre page d'accueil pour afficher les principales caractéristiques de votre projet. +Ajoutez l'attribut `stagger` pour décaler verticalement la deuxième colonne de cartes et ajouter un intérêt visuel : + +```astro +<CardGrid stagger> + <!-- cards --> +</CardGrid> +``` + +::: diff --git a/docs/src/content/docs/fr/guides/i18n.mdx b/docs/src/content/docs/fr/guides/i18n.mdx new file mode 100644 index 00000000..a5bb7715 --- /dev/null +++ b/docs/src/content/docs/fr/guides/i18n.mdx @@ -0,0 +1,201 @@ +--- +title: Internationalisation (i18n) +description: Apprenez à configurer votre site Starlight pour qu'il prenne en charge plusieurs langues. +--- + +import FileTree from '../../../../components/file-tree.astro'; + +Starlight offre une prise en charge intégrée des sites multilingues, y compris le routage, le contenu de repli et la prise en charge complète des langues de droite à gauche (RTL). + +## Configurer i18n + +1. Indiquez à Starlight les langues que vous prenez en charge en passant `locales` et `defaultLocale` à l'intégration Starlight : + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + // Définit l'anglais comme langue par défaut pour ce site. + defaultLocale: 'en', + locales: { + // Docs en anglais dans `src/content/docs/en/` + en: { + label: 'English', + }, + // Documentation en chinois simplifié dans `src/content/docs/zh/` + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + // docs en arabe dans `src/content/docs/ar/` + ar: { + label: 'العربية', + dir: 'rtl', + }, + }, + }), + ], + }); + ``` + + Votre `defaultLocale` sera utilisé pour le contenu de repli et les étiquettes de l'interface utilisateur, donc choisissez la langue dans laquelle vous êtes le plus susceptible de commencer à écrire du contenu, ou pour laquelle vous avez déjà du contenu. + +2. Créez un répertoire pour chaque langue dans `src/content/docs/`. + Par exemple, pour la configuration montrée ci-dessus, créez les dossiers suivants : + + <FileTree> + + - src/ + - content/ + - docs/ + - ar/ + - en/ + - zh/ + + </FileTree> + +3. Vous pouvez maintenant ajouter des fichiers de contenu dans vos répertoires de langues. Utilisez le même nom de fichier pour associer les pages d'une langue à l'autre et profiter de l'ensemble des fonctionnalités i18n de Starlight, y compris le contenu de repli, les avis de traduction, etc. + + Par exemple, créez `ar/index.md` et `en/index.md` pour représenter la page d'accueil en arabe et en anglais respectivement. + +### Utiliser une racine locale + +Vous pouvez utiliser une racine locale pour servir une langue sans aucun préfixe i18n dans son chemin. Par exemple, si l'anglais est votre racine locale, le chemin d'une page en anglais ressemblera à `/about` au lieu de `/en/about`. + +Pour définir une racine locale, utilisez la clé `root` dans votre configuration `locales`. Si la racine locale est aussi la locale par défaut de votre contenu, supprimez `defaultLocale` ou donnez-lui la valeur `'root''. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + defaultLocale: 'root', // optionnel + locales: { + root: { + label: 'English', + lang: 'en', // lang est nécessaire pour les locales de la racine + }, + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Lorsque vous utilisez une locale `root`, gardez les pages pour cette langue directement dans `src/content/docs/` au lieu d'un dossier dédié à la langue. Par exemple, voici les fichiers de la page d'accueil pour l'anglais et le chinois en utilisant la configuration ci-dessus : + +<FileTree> + +- src/ + - content/ + - docs/ + - **index.md** + - zh/ + - **index.md** + +</FileTree> + +#### Sites monolingues + +Par défaut, Starlight est un site monolingue (anglais). Pour créer un site monolingue dans une autre langue, définissez-la comme `root` dans votre configuration `locales` : + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Cela vous permet de remplacer la langue par défaut de Starlight sans activer d'autres fonctions d'internationalisation pour les sites multilingues, telles que le sélecteur de langue. + +## Contenu de remplacement + +Starlight s'attend à ce que vous créiez des pages équivalentes dans toutes vos langues. Par exemple, si vous avez un fichier `en/about.md`, créez un `about.md` pour chaque autre langue que vous supportez. Cela permet à Starlight de fournir un contenu de remplacement automatique pour les pages qui n'ont pas encore été traduites. + +Si une traduction n'est pas encore disponible pour une langue, Starlight affichera aux lecteurs le contenu de cette page dans la langue par défaut (définie via `defaultLocale`). Par exemple, si vous n'avez pas encore créé de version française de votre page À propos et que votre langue par défaut est l'anglais, les visiteurs de `/fr/about` verront le contenu anglais de `/en/about` avec un avis indiquant que cette page n'a pas encore été traduite. Cela vous permet d'ajouter du contenu dans votre langue par défaut et de le traduire progressivement lorsque vos traducteurs en ont le temps. + +## Traduire l'interface utilisateur de Starlight + +En plus d'héberger des fichiers de contenu traduits, Starlight vous permet de traduire les chaînes de l'interface utilisateur par défaut (par exemple, l'en-tête "Sur cette page" dans la table des matières) afin que vos lecteurs puissent découvrir votre site entièrement dans la langue sélectionnée. + +Les chaînes d'interface utilisateur traduites en anglais, allemand, japonais, portugais et espagnol sont fournies d'office, et nous acceptons les [contributions pour ajouter d'autres langues par défaut](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). + +Vous pouvez fournir des traductions pour les langues supplémentaires que vous supportez - ou remplacer nos étiquettes par défaut - via la collecte de données `i18n`. + +1. Configurez la collection de données `i18n` dans `src/content/config.ts` si elle n'est pas déjà configurée : + + ```js + // src/content/config.ts + import { defineCollection } from 'astro:content'; + import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; + + export const collections = { + docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), + }; + ``` + +2. Créez un fichier JSON dans `src/content/i18n/` pour chaque locale supplémentaire pour laquelle vous voulez fournir des chaînes de traduction pour l'interface utilisateur. + Par exemple, cela ajouterait des fichiers de traduction pour l'arabe et le chinois simplifié : + + <FileTree> + + - src/ + - content/ + - i18n/ + - ar.json + - zh-CN.json + + </FileTree> + +3. Ajoutez des traductions pour les clés que vous souhaitez traduire dans les fichiers JSON. Traduire uniquement les valeurs, en laissant les clés en anglais (e.g. `"search.label": "Buscar"`). + + Il s'agit des valeurs anglaises par défaut des chaînes de caractères existantes avec lesquelles Starlight est livré : + + ```json + { + "skipLink.label": "Aller au contenu", + "search.label": "rechercher", + "search.shortcutLabel": "(Presser / pour rechercher)", + "search.cancelLabel": "Annuler", + "themeSelect.accessibleLabel": "Selectionner le thème", + "themeSelect.dark": "Dark", + "themeSelect.light": "Light", + "themeSelect.auto": "Auto", + "languageSelect.accessibleLabel": "Selectionner la langue", + "menuButton.accessibleLabel": "Menu", + "sidebarNav.accessibleLabel": "Main", + "tableOfContents.onThisPage": "Sur cette page", + "tableOfContents.overview": "Vue d'ensemble", + "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", + "page.editLink": "Editer la page", + "page.lastUpdated": "Dernière mise à jour :", + "page.previousLink": "Suivant", + "page.nextLink": "Précédent" + } + ``` diff --git a/docs/src/content/docs/fr/guides/project-structure.mdx b/docs/src/content/docs/fr/guides/project-structure.mdx new file mode 100644 index 00000000..26322543 --- /dev/null +++ b/docs/src/content/docs/fr/guides/project-structure.mdx @@ -0,0 +1,48 @@ +--- +title: Structure du projet +description: Apprenez à organiser les fichiers dans votre projet Starlight. +--- + +Ce guide vous montrera comment un projet Starlight est organisé et ce que font les différents fichiers de votre projet. + +Les projets Starlight suivent généralement la même structure de fichiers et de répertoires que les autres projets Astro. Voir [la documentation sur la structure des projets Astro](https://docs.astro.build/fr/core-concepts/project-structure/) pour plus de détails. + +## Fichiers et répertoires + +- `astro.config.mjs` — Le fichier de configuration d'Astro ; inclut l'intégration et la configuration de Starlight. +- `src/content/config.ts` — Fichier de configuration des collections de contenu ; ajoute les schémas de la matière première de Starlight à votre projet. +- `src/content/docs/` — Fichiers de contenu. Starlight transforme chaque fichier `.md`, `.mdx` ou `.mdoc` de ce répertoire en une page de votre site. +- `src/content/i18n/` (optionnel) — Données de traduction pour prendre en charge l'[internationalisation](/fr/guides/i18n/). +- `src/` — Autre code source et fichiers (composants, styles, images, etc.) pour votre projet. +- `public/` — Actifs statiques (polices, favicon, PDFs, etc.) qui ne seront pas traités par Astro. + +## Exemple de contenu de projet + +Un répertoire de projet Starlight peut ressembler à ceci : + +import FileTree from '../../../../components/file-tree.astro'; + +<FileTree> + +- public/ + - favicon.svg +- src/ + - assets/ + - logo.svg + - screenshot.jpg + - components/ + - CustomButton.astro + - InteractiveWidget.jsx + - content/ + - docs/ + - guides/ + - 01-getting-started.md + - 02-advanced.md + - index.mdx + - config.ts + - env.d.ts +- astro.config.mjs +- package.json +- tsconfig.json + +</FileTree> diff --git a/docs/src/content/docs/fr/index.mdx b/docs/src/content/docs/fr/index.mdx new file mode 100644 index 00000000..b03ab4e0 --- /dev/null +++ b/docs/src/content/docs/fr/index.mdx @@ -0,0 +1,44 @@ +--- +title: Starlight 🌟 Construire des sites de documentation avec Astro +description: Starlight vous aide à créer de magnifiques sites web de documentation très performants avec Astro. +template: splash +hero: + title: Faites briller vos documents avec Starlight + tagline: Tout ce dont vous avez besoin pour créer un excellent site web de documentation. Rapide, accessible et facile à utiliser. + image: + file: ../../../assets/hero-star.webp + actions: + - text: Mise en route + icon: right-arrow + variant: primary + link: /fr/getting-started/ + - text: Voir sur GitHub + icon: external + link: https://github.com/withastro/starlight +--- + +import { CardGrid, Card } from '@astrojs/starlight/components'; +import AboutAstro from '../../../components/about-astro.astro'; + +<CardGrid stagger> + <Card title="Une documentation qui enchante" icon="open-book"> + Comprend : Navigation dans le site, recherche, internationalisation, référencement naturel, typographie facile à lire, mise en évidence du code, mode sombre, etc. + </Card> + <Card title="Propulsé par Astro" icon="rocket"> + Exploitez toute la puissance et les performances d'Astro. Étendez Starlight avec vos intégrations et bibliothèques Astro préférées. + </Card> + <Card title="Markdown, Markdoc, et MDX" icon="document"> + Apportez votre langage de balisage préféré. Starlight vous offre une validation frontmatter intégrée avec la sécurité de type TypeScript. + </Card> + <Card title="Apportez vos propres composants d'interface utilisateur" icon="puzzle"> + Starlight est une solution de documentation complète, indépendante du cadre de travail. Étendez avec React, Vue, Svelte, Solid, et plus encore. + </Card> +</CardGrid> + +<AboutAstro title="Présenté par"> +Astro est le framework web tout-en-un conçu pour la vitesse. +Tirez votre contenu de n'importe où et déployez-le partout, le tout alimenté par vos composants et bibliothèques d'interface utilisateur préférés. + +[En savoir plus sur Astro](https://astro.build/) + +</AboutAstro> diff --git a/docs/src/content/docs/fr/reference/configuration.md b/docs/src/content/docs/fr/reference/configuration.md new file mode 100644 index 00000000..4e6ab2f9 --- /dev/null +++ b/docs/src/content/docs/fr/reference/configuration.md @@ -0,0 +1,326 @@ +--- +title: Référence de configuration +description: Une vue d'ensemble de toutes les options de configuration prises en charge par Starlight. +--- + +## Configuration de l'intégration `starlight` + +Starlight est une intégration construite sur le framework web [Astro](https://astro.build). Vous pouvez configurer votre projet dans le fichier de configuration Astro `astro.config.mjs` : + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: "Mon délicieux site de docs", + }), + ], +}); +``` + +Vous pouvez passer les options suivantes à l'intégration `starlight`. + +### `title` (obligatoire) + +**type:** `string` + +Définissez le titre de votre site web. Il sera utilisé dans les métadonnées et dans le titre de l'onglet du navigateur. + +### `description` + +**type:** `string` + +Définissez la description de votre site web. Utilisée dans les métadonnées partagées avec les moteurs de recherche dans la balise `<meta name="description">` si `description` n'est pas définie dans le frontmatter d'une page. + +### `logo` + +**type:** [`LogoConfig`](#logoconfig) + +Définit une image de logo à afficher dans la barre de navigation à côté ou à la place du titre du site. Vous pouvez soit définir une seule propriété `src`, soit définir des sources d'images séparées pour `light` et `dark`. + +```js +starlight({ + logo: { + src: '/src/assets/my-logo.svg', + }, +}); +``` + +#### `LogoConfig` + +```ts +type LogoConfig = { alt?: string; replacesTitle?: boolean } & ( + | { src: string } + | { light: string; dark: string } +); +``` + +### `tableOfContents` + +**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` +**default:** `{ minHeadingLevel: 2; maxHeadingLevel: 3; }` + +Configurez la table des matières affichée à droite de chaque page. Par défaut, les titres `<h2>` et `<h3>` seront inclus dans cette table des matières. + +### `editLink` + +**type:** `{ baseUrl: string }` + +Permet d'activer les liens "Modifier cette page" en définissant l'URL de base qu'ils doivent utiliser. Le lien final sera `editLink.baseUrl` + le chemin de la page actuelle. Par exemple, pour permettre l'édition de pages dans le repo `withastro/starlight` sur GitHub : + +```js +starlight({ + editLink: { + baseUrl: 'https://github.com/withastro/starlight/edit/main/', + }, +}); +``` + +Avec cette configuration, une page `/introduction` aurait un lien d'édition pointant vers `https://github.com/withastro/starlight/edit/main/src/docs/introduction.md`. + +### `sidebar` + +**type:** [`SidebarGroup[]`](#sidebargroup) + +Configure les éléments de navigation de la barre latérale de votre site. + +Une barre latérale est un tableau de groupes, chacun avec un `label` pour le groupe et un tableau `items` ou un objet de configuration `autogenerate`. + +Vous pouvez définir manuellement le contenu d'un groupe en utilisant `items`, qui est un tableau pouvant inclure des liens et des sous-groupes. Vous pouvez aussi générer automatiquement le contenu d'un groupe à partir d'un répertoire spécifique de votre documentation, en utilisant `autogenerate`. + +```js +starlight({ + sidebar: [ + // Un groupe intitulé "Commencer ici" contenant deux liens. + { + label: 'Commencer ici', + items: [ + { label: 'Introduction', link: '/intro' }, + { label: 'Etapes', link: '/next-steps' }, + ], + }, + // Un groupe qui renvoie à toutes les pages du répertoire de référence. + { + label: 'Référence', + autogenerate: { directory: 'reference' }, + }, + ], +}); +``` + +#### Tri + +Les groupes de barres latérales générées automatiquement sont triés par nom de fichier et par ordre alphabétique. +Par exemple, une page générée à partir de `astro.md` apparaîtrait au-dessus de la page de `starlight.md`. + +#### Traduire les étiquettes + +Si votre site est multilingue, le `label` de chaque élément est considéré comme étant dans la locale par défaut. Vous pouvez définir une propriété `translations` pour fournir des étiquettes pour les autres langues supportées : + +```js +sidebar: [ + // Un exemple de barre latérale avec des étiquettes traduites en anglais. + { + label: 'Commencer ici', + translations: { en: 'Start here' }, + items: [ + { + label: 'Bien démarrer', + translations: { en: 'Getting Started' }, + link: '/getting-started', + }, + { + label: 'Structure du projet', + translations: { en: 'Project Structure' }, + link: '/structure', + }, + ], + }, +]; +``` + +#### `SidebarGroup` + +```ts +type SidebarGroup = + | { + label: string; + translations?: Record<string, string>; + items: Array<LinkItem | SidebarGroup>; + } + | { + label: string; + translations?: Record<string, string>; + autogenerate: { + directory: string; + }; + }; +``` + +#### `LinkItem` + +```ts +interface LinkItem { + label: string; + link: string; +} +``` + +### `locales` + +**type:** `{ [dir: string]: LocaleConfig }` + +Configurez l'internationalisation (i18n) de votre site en définissant les `locales` supportées. + +Chaque entrée doit utiliser comme clé le répertoire dans lequel les fichiers de cette langue sont sauvegardés. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My Site', + // Définit l'anglais comme langue par défaut pour ce site. + defaultLocale: 'en', + locales: { + // Documentations en anglais danse trouve dans `src/content/docs/en/` + en: { + label: 'English', + }, + // Documentations en Chinois simplifié se trouve dans `src/content/docs/zh/` + zh: { + label: '简体中文', + lang: 'zh-CN', + }, + // Documentations en Arabe se trouve dans `src/content/docs/ar/` + ar: { + label: 'العربية', + dir: 'rtl', + }, + }, + }), + ], +}); +``` + +#### Options des paramètres linguistiques + +Vous pouvez définir les options suivantes pour chaque locale : + +##### `label` (obligatoire) + +**type:** `string` + +L'étiquette de cette langue à afficher aux utilisateurs, par exemple dans le sélecteur de langue. Le plus souvent, il s'agit du nom de la langue tel qu'un utilisateur de cette langue s'attendrait à le lire, par exemple `"English"`, `"العربية"`, ou `"简体中文"`. + +##### `lang` + +**type:** `string` + +La balise BCP-47 pour cette langue, par exemple `"en"`, `"ar"`, ou `"zh-CN"`. S'il n'est pas défini, le nom du répertoire de la langue sera utilisé par défaut. + +##### `dir` + +**type:** `'ltr' | 'rtl'` + +Le sens d'écriture de cette langue ; `"ltr"` pour gauche à droite (par défaut) ou `"rtl"` pour droite à gauche. + +#### Locale racine + +Vous pouvez servir la langue par défaut sans répertoire `/lang/` en définissant une locale `root` : + +```js +starlight({ + locales: { + root: { + label: 'English', + lang: 'en', + }, + fr: { + label: 'Français', + }, + }, +}); +``` + +Par exemple, cela vous permet de servir `/getting-started/` comme une route anglaise et d'utiliser `/fr/getting-started/` comme la page française équivalente. + +### `defaultLocale` + +**type:** `string` + +Définit la langue par défaut pour ce site. +La valeur doit correspondre à l'une des clés de votre objet [`locales`](#locales). +(Si votre langue par défaut est votre [root locale](#root-locale), vous pouvez sauter cette étape). + +La locale par défaut sera utilisée pour fournir un contenu de remplacement lorsque les traductions sont manquantes. + +### `social` + +**type:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }` + +Détails optionnels sur les comptes de médias sociaux pour ce site. L'ajout de l'un d'entre eux les affichera sous forme de liens iconiques dans l'en-tête du site. + +```js +starlight({ + social: { + discord: 'https://astro.build/chat', + github: 'https://github.com/withastro/starlight', + mastodon: 'https://m.webtoo.ls/@astro', + twitter: 'https://twitter.com/astrodotbuild', + }, +}); +``` + +### `customCss` + +**type:** `string[]` + +Fournit des fichiers CSS pour personnaliser l'aspect et la convivialité de votre site Starlight. + +Prend en charge les fichiers CSS locaux relatifs à la racine de votre projet, par exemple `'/src/custom.css'`, et les CSS que vous avez installés en tant que module npm, par exemple `'@fontsource/roboto'`. + +```js +starlight({ + customCss: ['/src/custom-styles.css', '@fontsource/roboto'], +}); +``` + +### `head` + +**type:** [`HeadConfig[]`](#headconfig) + +Ajoute des balises personnalisées au `<head>` de votre site Starlight. +Cela peut être utile pour ajouter des analyses et d'autres scripts et ressources tiers. + +```js +starlight({ + head: [ + // Exemple : ajouter un script d'analyse Fathom tag. + { + tag: 'script', + attrs: { + src: 'https://cdn.usefathom.com/script.js', + 'data-site': 'MY-FATHOM-ID', + defer: true, + }, + }, + ], +}); +``` + +#### `HeadConfig` + +```ts +interface HeadConfig { + tag: string; + attrs?: Record<string, string | boolean | undefined>; + content?: string; +} +``` diff --git a/docs/src/content/docs/fr/reference/frontmatter.md b/docs/src/content/docs/fr/reference/frontmatter.md new file mode 100644 index 00000000..6a8bdc3f --- /dev/null +++ b/docs/src/content/docs/fr/reference/frontmatter.md @@ -0,0 +1,119 @@ +--- +title: Frontmatter Reference +description: Une vue d'ensemble des champs frontmatter par défaut pris en charge par Starlight. +--- + +Vous pouvez personnaliser des pages Markdown et MDX individuelles dans Starlight en définissant des valeurs dans leur page de garde. Par exemple, une page normale peut définir les champs `title` et `description` : + +```md +--- +title: A propos de ce projet +description: En savoir plus sur le projet sur lequel je travaille. +--- + +Bienvenue sur la page "à propos" ! +``` + +## Champs de la page d'accueil + +### `title` (obligatoire) + +**type:** `string` + +Vous devez fournir un titre pour chaque page. Il sera affiché en haut de la page, dans les onglets du navigateur et dans les métadonnées de la page. + +### `description` + +**type:** `string` + +La description de la page est utilisée pour les métadonnées de la page et sera reprise par les moteurs de recherche et dans les aperçus des médias sociaux. + +### `editUrl` + +**type:** `string | boolean` + +Remplace la [configuration globale `editLink`](/fr/reference/configuration/#editlink). Mettez `false` pour désactiver le lien "Editer la page" pour une page spécifique ou pour fournir une URL alternative où le contenu de cette page est éditable. + +### `head` + +**type:** [`HeadConfig[]`](/fr-FR/reference/configuration/#headconfig) + +Vous pouvez ajouter des balises supplémentaires au champ `<head>` de votre page en utilisant le champ `head` frontmatter. Cela signifie que vous pouvez ajouter des styles personnalisés, des métadonnées ou d'autres balises à une seule page. Similaire à [l'option globale `head`](/fr/reference/configuration/#head). + +```md +--- +title: A propos de nous +head: + # Utiliser une balise <title> personnalisée + - tag: title + content: Titre personnalisé à propos de nous +--- +``` + +### `tableOfContents` + +**type:** `false | { minHeadingLevel?: number; maxHeadingLevel?: number; }` + +Remplace la [configuration globale `tableOfContents`](/fr/reference/configuration/#tableofcontents). +Personnalisez les niveaux d'en-tête à inclure ou mettez `false` pour cacher la table des matières sur cette page. + +### `template` + +**type:** `'doc' | 'splash'` +**default:** `'doc'` + +Définit le modèle de mise en page pour cette page. +Les pages utilisent la mise en page `'doc'`' par défaut. +La valeur `'splash''` permet d'utiliser une mise en page plus large, sans barres latérales, conçue pour les pages d'atterrissage. + +### `hero` + +**type:** [`HeroConfig`](#heroconfig) + +Ajoute un composant héros en haut de la page. Fonctionne bien avec `template : splash`. + +Par exemple, cette configuration montre quelques options communes, y compris le chargement d'une image depuis votre dépôt. + +```md +--- +title: Ma page d'accueil +template: splash +hero: + title: 'Mon projet : Stellar Stuffer Sooner' + tagline: Emmenez vos affaires sur la lune et revenez-y en un clin d'œil. + image: + alt: Un logo aux couleurs vives et scintillantes + file: ../../assets/logo.png + actions: + - text: En savoir plus + link: /getting-started/ + icon: right-arrow + variant: primary + - text: Voir sur GitHub + link: https://github.com/astronaut/my-project + icon: external +--- +``` + +#### `HeroConfig` + +```ts +interface HeroConfig { + title?: string; + tagline?: string; + image?: { + alt?: string; + // Chemin relatif vers une image dans votre référentiel. + file?: string; + // HTML brut à utiliser dans l'emplacement de l'image. + // Il peut s'agir d'une balise `<img>` personnalisée ou d'une balise `<svg>` en ligne. + html?: string; + }; + actions?: Array<{ + text: string; + link: string; + variant: 'primary' | 'secondary' | 'minimal'; + icon: string; + }>; +} +``` -- cgit From db9eb7aa367c7ac6217677914d06ba6159a33e7d Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Mon, 5 Jun 2023 20:00:30 +0200 Subject: Add query param to OG image because Twitter is bad (#156) --- docs/astro.config.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 076ad398..63073ee4 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -31,11 +31,11 @@ export default defineConfig({ }, { tag: 'meta', - attrs: { property: 'og:image', content: site + 'og.jpg' }, + attrs: { property: 'og:image', content: site + 'og.jpg?v=1' }, }, { tag: 'meta', - attrs: { property: 'twitter:image', content: site + 'og.jpg' }, + attrs: { property: 'twitter:image', content: site + 'og.jpg?v=1' }, }, ], customCss: process.env.NO_GRADIENTS ? [] : ['/src/assets/landing.css'], -- cgit From 5f901aade8e7be57368c7f3e381b37b36323cf64 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 22:03:19 +0200 Subject: "des sites de documentations" to "des documentations" --- docs/src/content/docs/fr/environmental-impact.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/fr/environmental-impact.md b/docs/src/content/docs/fr/environmental-impact.md index f9c8c919..9e552f60 100644 --- a/docs/src/content/docs/fr/environmental-impact.md +++ b/docs/src/content/docs/fr/environmental-impact.md @@ -1,6 +1,6 @@ --- title: Documents écologiques -description: Découvrez comment Starlight peut vous aider à créer des sites de documentation plus écologiques et à réduire votre empreinte carbone. +description: Découvrez comment Starlight peut vous aider à créer des documentations plus écologiques et à réduire votre empreinte carbone. --- Les estimations de l'impact climatique de l'industrie du web varient entre [2 %][sf] et [4 % des émissions mondiales de carbone][bbc], ce qui équivaut à peu près aux émissions de l'industrie du transport aérien. -- cgit From c1235b008b3b5e2212468cbcd7905873ea280da5 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Mon, 5 Jun 2023 22:24:03 +0200 Subject: Adding packages/translations/fr.json --- packages/starlight/translations/fr.json | 20 ++++++++++++++++++++ packages/starlight/translations/index.ts | 3 ++- 2 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 packages/starlight/translations/fr.json diff --git a/packages/starlight/translations/fr.json b/packages/starlight/translations/fr.json new file mode 100644 index 00000000..91be0788 --- /dev/null +++ b/packages/starlight/translations/fr.json @@ -0,0 +1,20 @@ +{ + "skipLink.label": "Aller au contenu", + "search.label": "rechercher", + "search.shortcutLabel": "(Presser / pour rechercher)", + "search.cancelLabel": "Annuler", + "themeSelect.accessibleLabel": "Selectionner le thème", + "themeSelect.dark": "Dark", + "themeSelect.light": "Light", + "themeSelect.auto": "Auto", + "languageSelect.accessibleLabel": "Selectionner la langue", + "menuButton.accessibleLabel": "Menu", + "sidebarNav.accessibleLabel": "Main", + "tableOfContents.onThisPage": "Sur cette page", + "tableOfContents.overview": "Vue d'ensemble", + "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", + "page.editLink": "Editer la page", + "page.lastUpdated": "Dernière mise à jour :", + "page.previousLink": "Suivant", + "page.nextLink": "Précédent" + } \ No newline at end of file diff --git a/packages/starlight/translations/index.ts b/packages/starlight/translations/index.ts index c721633d..ee16ba32 100644 --- a/packages/starlight/translations/index.ts +++ b/packages/starlight/translations/index.ts @@ -4,9 +4,10 @@ import es from './es.json'; import de from './de.json'; import ja from './ja.json'; import pt from './pt.json'; +import fr from './fr.json'; const parse = i18nSchema().required().strict().parse; export default Object.fromEntries( - Object.entries({ en, es, de, ja, pt }).map(([key, dict]) => [key, parse(dict)]) + Object.entries({ en, es, de, ja, pt, fr }).map(([key, dict]) => [key, parse(dict)]) ); -- cgit From c69c2c1453c08fcde4776eb5724a726fe3bd1f72 Mon Sep 17 00:00:00 2001 From: Kevin Zuniga Cuellar Date: Mon, 5 Jun 2023 16:34:00 -0400 Subject: word break bby --- packages/starlight/components/Search.astro | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro index d01415ac..d3403404 100644 --- a/packages/starlight/components/Search.astro +++ b/packages/starlight/components/Search.astro @@ -294,6 +294,7 @@ const t = useTranslations(Astro.props.locale); #starlight__search .pagefind-ui__result-excerpt { font-size: var(--sl-text-body-sm); + word-break: break-all; } #starlight__search mark { -- cgit From 8c75a4c46f51eaee8f5576c6f25656a471e51301 Mon Sep 17 00:00:00 2001 From: Marc Date: Mon, 5 Jun 2023 22:50:43 +0200 Subject: i18n(de): add getting-started.mdx (#153) --- docs/astro.config.mjs | 11 +++- docs/src/content/docs/de/getting-started.mdx | 87 ++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 docs/src/content/docs/de/getting-started.mdx diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 63073ee4..b501e42b 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -57,12 +57,19 @@ export default defineConfig({ { label: 'Getting Started', link: 'getting-started', - translations: { es: "Empezando", ja: '入門' }, + translations: { + de: 'Erste Schritte', + es: 'Empezando', + ja: '入門', + }, }, { label: 'Environmental Impact', link: 'environmental-impact', - translations: { es: "Documentación ecológica", ja: '環境への負荷' }, + translations: { + es: 'Documentación ecológica', + ja: '環境への負荷', + }, }, ], }, diff --git a/docs/src/content/docs/de/getting-started.mdx b/docs/src/content/docs/de/getting-started.mdx new file mode 100644 index 00000000..47cf01c4 --- /dev/null +++ b/docs/src/content/docs/de/getting-started.mdx @@ -0,0 +1,87 @@ +--- +title: Erste Schritte +description: Lerne wie du deine nächste Dokumentationsseite mit Starlight und Astro erstellst. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +:::caution[In Arbeit] +Starlight befindet sich in einer frühen Entwicklungsphase. +Wenn du etwas findest, das nicht funktioniert, [öffne ein Issue auf GitHub](https://github.com/withastro/starlight/issues/new/choose) oder lass es uns bei [Discord](https://astro.build/chat) wissen. +::: + +## Erstelle ein neues Projekt + +Starlight ist ein voll ausgestattetes Dokumentations-Theme, das auf dem [Astro](https://astro.build) Framework aufbaut. + +Du kannst ein neues Astro + Starlight Projekt mit dem folgenden Befehl erstellen: + +<Tabs> +<TabItem label="npm"> + +```sh +# Erstelle ein neues Projekt mit npm +npm create astro@latest -- --template starlight +``` + +</TabItem> +<TabItem label="pnpm"> + +```sh +# Erstelle ein neues Projekt mit pnpm +pnpm create astro --template starlight +``` + +</TabItem> +<TabItem label="Yarn"> + +```sh +# Erstelle ein neues Projekt mit yarn +yarn create astro --template starlight +``` + +</TabItem> +</Tabs> + +Damit wird ein neues [Projektverzeichnis](/de/guides/project-structure/) mit allen erforderlichen Dateien und Konfigurationen für deine Webseite erstellt. + +:::tip[In Aktion sehen] +Probiere Starlight in deinem Browser aus: +[öffne die Vorlage in StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics). +::: + +## Inhalte mit Starlight erstellen + +Starlight ist bereit für dich, neuen Inhalt hinzuzufügen oder deine vorhandenen Dateien mitzubringen! + +### Dateiformate + +Starlight unterstützt das Erstellen von Inhalten in Markdown und MDX. (Du kannst die experimentelle [Astro Markdoc Integration](https://docs.astro.build/de/guides/integrations-guide/markdoc/) installieren, um Markdoc zu unterstützen.) + +### Seiten hinzufügen + +Füge neue Seiten zu deiner Webseite automatisch hinzu, indem du `.md` oder `.mdx` Dateien in `src/content/docs/` erstellst. Erstelle Unterordner, um deine Dateien zu organisieren und mehrere Pfadsegmente zu erstellen: + +```js +`src/content/docs/hello-world.md` -> `your-site/hello-world` +`src/content/docs/guides/faq.md` -> `your-site/guides/faq` +``` + +### Typsichere Frontmatter + +Alle Starlight Seiten teilen sich anpassbare [Frontmatter-Eigenschaften](/de/reference/frontmatter/), mit denen das Erscheinungsbild der Seite gesteuert wird: + +```md +--- +title: Hello, World! +description: This is a page in my Starlight-powered site +--- +``` + +Wenn du etwas Wichtiges vergisst, wird Starlight dich daran erinnern. + +## Veröffentlichung deiner Starlight Webseite + +Sobald du deine Starlight Webseite erstellt und angepasst hast, kannst du sie auf einen Webserver oder Hosting-Plattform deiner Wahl veröffentlichen, einschließlich Netlify, Vercel, GitHub Pages und vielen mehr. + +[Lerne mehr über die Veröffentlichung einer Astro Webseite in der Astro Dokumentation.](https://docs.astro.build/de/guides/deploy/) -- cgit From 92d82f534c6ff8513b01f9f26748d9980a6d4c79 Mon Sep 17 00:00:00 2001 From: Kevin Zuniga Cuellar Date: Mon, 5 Jun 2023 17:36:44 -0400 Subject: add changeset --- .changeset/swift-files-retire.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/swift-files-retire.md diff --git a/.changeset/swift-files-retire.md b/.changeset/swift-files-retire.md new file mode 100644 index 00000000..1ea3a1c9 --- /dev/null +++ b/.changeset/swift-files-retire.md @@ -0,0 +1,5 @@ +--- +"@astrojs/starlight": patch +--- + +Improve word wrapping for optimal display on smaller mobile screens -- cgit From b5b8980ed0e0f6d4614dff1fda41e3ec77105478 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Mon, 5 Jun 2023 23:58:02 +0200 Subject: Use overflow-wrap instead of word-break --- packages/starlight/components/Search.astro | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro index d3403404..8c035460 100644 --- a/packages/starlight/components/Search.astro +++ b/packages/starlight/components/Search.astro @@ -294,7 +294,7 @@ const t = useTranslations(Astro.props.locale); #starlight__search .pagefind-ui__result-excerpt { font-size: var(--sl-text-body-sm); - word-break: break-all; + overflow-wrap: break-word; } #starlight__search mark { -- cgit From b34cc1db14fde204d066c7b6c5d82511bfdea9d3 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 6 Jun 2023 00:05:53 +0200 Subject: Update changeset --- .changeset/swift-files-retire.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/swift-files-retire.md b/.changeset/swift-files-retire.md index 1ea3a1c9..497e3c9e 100644 --- a/.changeset/swift-files-retire.md +++ b/.changeset/swift-files-retire.md @@ -2,4 +2,4 @@ "@astrojs/starlight": patch --- -Improve word wrapping for optimal display on smaller mobile screens +Fix word wrapping in search modal on narrow screens -- cgit From 67ffe9c5aeaf6bc6d21f9e23107ad5f241d1a4cb Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Tue, 6 Jun 2023 00:06:21 +0200 Subject: wrd-brk: brk-wrd --- packages/starlight/components/Search.astro | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro index 8c035460..5988320f 100644 --- a/packages/starlight/components/Search.astro +++ b/packages/starlight/components/Search.astro @@ -294,7 +294,7 @@ const t = useTranslations(Astro.props.locale); #starlight__search .pagefind-ui__result-excerpt { font-size: var(--sl-text-body-sm); - overflow-wrap: break-word; + word-break: break-word; } #starlight__search mark { -- cgit From 3d86e1c3092b83ecd3cf7d14859bf829eb5952a8 Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Tue, 6 Jun 2023 09:50:19 +0900 Subject: i18n(ja): Add authoring-content.md --- .../content/docs/ja/guides/authoring-content.md | 211 +++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 docs/src/content/docs/ja/guides/authoring-content.md diff --git a/docs/src/content/docs/ja/guides/authoring-content.md b/docs/src/content/docs/ja/guides/authoring-content.md new file mode 100644 index 00000000..e652c42f --- /dev/null +++ b/docs/src/content/docs/ja/guides/authoring-content.md @@ -0,0 +1,211 @@ +--- +title: Markdownでのコンテンツ作成 +description: StarlightがサポートするMarkdown構文の概要。 +--- + +Starlightでは、`.md`ファイルにおいて[Markdown](https://daringfireball.net/projects/markdown/)構文のすべての機能を利用できます。また、タイトルや説明文（description）などのメタデータを定義するためのフロントマター[YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f)もサポートしています。 + +MDXやMarkdocを使用する場合、サポートされるMarkdownの機能や使用方法が異なることがあるため、[MDXドキュメント](https://mdxjs.com/docs/what-is-mdx/#markdown)や[Markdocドキュメント](https://markdoc.dev/docs/syntax)を必ず確認してください。 + +## インラインスタイル + +テキストは**太字**、_斜体_、または~~取り消し線~~にできます。 + +```md +テキストは**太字**、_斜体_、または~~取り消し線~~にできます。 +``` + +[別のページにリンク](/ja/getting-started/)できます。 + +```md +[別のページにリンク](/ja/getting-started/)できます。 +``` + +バックティックで`インラインコード`を強調できます。 + +```md +バックティックで`インラインコード`を強調できます。 +``` + +## 画像 + +Starlightは、Astro組み込みのアセット最適化機能を使用して画像を表示します。 + +MarkdownとMDXは、スクリーンリーダーや支援技術のための代替テキストを含む画像を表示するためのMarkdown構文をサポートしています。 + +![「astro」という単語を中心に据えた惑星と恒星のイラスト](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) + +```md +![「astro」という単語を中心に据えた惑星と恒星のイラスト](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png) +``` + +プロジェクトにローカルに保存されている画像についても、相対パスを使用して表示できます。 + +```md +// src/content/docs/page-1.md + +![宇宙空間に浮かぶロケット。](../../assets/images/rocket.svg) +``` + + +## 見出し + +見出しによりコンテンツを構造化できます。Markdownの見出しは、行の先頭にある`#`の数で示されます。 + +### ページコンテンツを構造化する方法 + +Starlightは、ページタイトルをトップレベルの見出しとして自動的に使用し、また各ページの目次の先頭に「概要」という見出しを含めます。各ページを通常のテキストコンテンツで開始し、ページ上の見出しは`<h2>`以下を使用することをおすすめします。 + +```md +--- +title: Markdownガイド +description: StarlightでのMarkdownの使い方 +--- + +このページでは、StarlightでMarkdownを使用する方法について説明します。 + +## インラインスタイル + +## 見出し + +``` + +### 見出しの自動アンカーリンク + +Markdownで見出しを使用するとアンカーリンクが自動的に付与されるため、ページの特定のセクションに直接リンクできます。 + +```md +--- +title: 私のページコンテンツ +description: Starlightの組み込みアンカーリンクの使い方 +--- +## はじめに + +同じページの下部にある[結論](#結論)にリンクできます。 + +## 結論 + +`https://my-site.com/page1/#はじめに`は、「はじめに」に直接移動します。 +``` + +レベル2（`<h2>`）とレベル3（`<h3>`）の見出しは、ページの目次に自動的に表示されます。 + + +## 補足情報 + +補足情報（「警告」や「吹き出し」とも呼ばれます）は、ページのメインコンテンツと並べて補助的な情報を表示するのに便利です。 + +Starlightは、補足情報をレンダリングするためのカスタムMarkdown構文を提供しています。補足情報のブロックは、コンテンツを囲む3つのコロン`:::`によって示し、`note`（注釈）、`tip`（ヒント）、`caution`（注意）、`danger`（危険）というタイプに設定できます。 + +他のMarkdownコンテンツを補足情報の中にネストできますが、補足情報は短く簡潔なコンテンツに最も適しています。 + +### 注釈 + +:::note +Starlightは、[Astro](https://astro.build/)製のドキュメントサイト用ツールキットです。次のコマンドではじめられます。 + +```sh +npm create astro@latest -- --template starlight +``` + +::: + +````md +:::note +Starlightは、[Astro](https://astro.build/)製のドキュメントサイト用ツールキットです。次のコマンドではじめられます。 + +```sh +npm create astro@latest -- --template starlight +``` + +::: +```` + +### カスタムのタイトル + +補足情報のカスタムタイトルを、補足情報のタイプの後ろに角括弧で囲んで指定できます。たとえば`:::tip[ご存知でしたか？]`のようにできます。 + +:::tip[ご存知でしたか？] +Astroでは[「アイランドアーキテクチャ」](https://docs.astro.build/ja/concepts/islands/)を使用して、より高速なWebサイトを構築できます。 +::: + +```md +:::tip[ご存知でしたか？] +Astroでは[「アイランドアーキテクチャ」](https://docs.astro.build/ja/concepts/islands/)を使用して、より高速なWebサイトを構築できます。 +::: +``` + +### その他のタイプ + +注意（Caution）と危険（Danger）の補足は、ユーザーがつまずく可能性のある細かい点に注意を向けさせるのに役立ちます。もしこれらを多用しているとすれば、それはあなたがドキュメントを書いている対象の設計を見直す余地があることのサインかもしれません。 + +:::caution +もしあなたが素晴らしいドキュメントサイトを望んでいないのであれば、[Starlight](../../)は不要かもしれません。 +::: + +:::danger +Starlightの便利な機能のおかげで、ユーザーはより生産的になり、プロダクトはより使いやすくなるかもしれません。 + +- わかりやすいナビゲーション +- ユーザーが設定可能なカラーテーマ +- [国際化機能](/ja/guides/i18n) + +::: + +```md +:::caution +もしあなたが素晴らしいドキュメントサイトを望んでいないのであれば、[Starlight](../../)は不要かもしれません。 +::: + +:::danger +Starlightの便利な機能のおかげで、ユーザーはより生産的になり、プロダクトはより使いやすくなるかもしれません。 + +- わかりやすいナビゲーション +- ユーザーが設定可能なカラーテーマ +- [国際化機能](/ja/guides/i18n) + +::: +``` + +## 引用 + +> これは引用です。他の人の言葉やドキュメントを引用するときによく使われます。 +> +> 引用は、各行の先頭に`>`を付けることで示されます。 + +```md +> これは引用です。他の人の言葉やドキュメントを引用するときによく使われます。 +> +> 引用は、各行の先頭に`>`を付けることで示されます。 +``` + +## コード + +コードのブロックは、先頭と末尾に3つのバックティック<code>```</code>を持つブロックで示されます。コードブロックを開始するバックティックの後ろに、使用されているプログラミング言語を指定できます。 + +```js +// シンタックスハイライトされたJavascriptコード。 +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` + +````md +```js +// シンタックスハイライトされたJavascriptコード。 +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` +```` + +```md +長い1行のコードブロックは折り返されません。長すぎる場合は、水平方向にスクロールする必要があります。この行は、このことを示すのに十分な長さであるはずです。 +``` + +## その他のMarkdown機能 + +Starlightは、リストやテーブルなど、その他のMarkdown記法をすべてサポートしています。Markdownのすべての構文要素の概要については、[The Markdown GuideのMarkdownチートシート](https://www.markdownguide.org/cheat-sheet/)を参照してください。 + -- cgit From 0012f311695212efccfe206a8705630c1b48c3dd Mon Sep 17 00:00:00 2001 From: Shinya Fujino Date: Tue, 6 Jun 2023 09:55:45 +0900 Subject: Fix npm create command in authoring-content.md --- docs/src/content/docs/guides/authoring-content.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/guides/authoring-content.md b/docs/src/content/docs/guides/authoring-content.md index bfeb044e..52896a03 100644 --- a/docs/src/content/docs/guides/authoring-content.md +++ b/docs/src/content/docs/guides/authoring-content.md @@ -104,7 +104,7 @@ You can nest any other Markdown content types inside an aside, but asides are be Starlight is a documentation website toolkit built with [Astro](https://astro.build/). You can get started with this command: ```sh -npm run create astro@latest --template starlight +npm create astro@latest -- --template starlight ``` ::: @@ -114,7 +114,7 @@ npm run create astro@latest --template starlight Starlight is a documentation website toolkit built with [Astro](https://astro.build/). You can get started with this command: ```sh -npm run create astro@latest --template starlight +npm create astro@latest -- --template starlight ``` ::: -- cgit From c44cca6dc92c0cacf05f2a1bea274085857efd55 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Tue, 6 Jun 2023 12:30:41 +0200 Subject: Update docs/src/content/docs/fr/getting-started.mdx Co-authored-by: Maxime <iverly.dev@gmail.com>--- docs/src/content/docs/fr/getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/fr/getting-started.mdx b/docs/src/content/docs/fr/getting-started.mdx index a9ab610b..d076bc49 100644 --- a/docs/src/content/docs/fr/getting-started.mdx +++ b/docs/src/content/docs/fr/getting-started.mdx @@ -52,7 +52,7 @@ Essayez Starlight dans votre navigateur : ## Créer du contenu avec Starlight -Starlight est prêt pour que vous puissiez ajouter du nouveau contenu, ou apporter vos fichiers existants ! +Starlight est conçu pour que vous puissiez ajouter du nouveau contenu, ou apporter vos fichiers existants ! ### Formats de fichiers -- cgit From 3c128202be6e8526358b50107054068584e50b6c Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Tue, 6 Jun 2023 12:30:58 +0200 Subject: Update docs/src/content/docs/fr/guides/authoring-content.md Co-authored-by: Maxime <iverly.dev@gmail.com>--- docs/src/content/docs/fr/guides/authoring-content.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/src/content/docs/fr/guides/authoring-content.md b/docs/src/content/docs/fr/guides/authoring-content.md index 4a062b93..35a11763 100644 --- a/docs/src/content/docs/fr/guides/authoring-content.md +++ b/docs/src/content/docs/fr/guides/authoring-content.md @@ -135,8 +135,7 @@ Astro vous aide à construire des sites Web plus rapides grâce à ["Islands Arc ### Plus de types pour l'aside -Les apartés de type Attention et Danger sont utiles pour attirer l'attention de l'utilisateur sur des détails qui pourraient le faire trébucher. -Si vous les utilisez souvent, c'est peut-être aussi le signe que la chose que vous documentez gagnerait à être repensée. +Les apartés de type Attention et Danger sont utiles pour attirer l'attention de l'utilisateur sur des détails qui pourraient le perturber. Si vous vous retrouvez à utiliser ces derniers fréquemment, cela pourrait aussi être un signe que ce que vous documentez pourrait bénéficier d'une refonte. :::caution Si vous n'êtes pas sûr de vouloir un site de documentation génial, réfléchissez à deux fois avant d'utiliser [Starlight](../../../). -- cgit From a3465dfae029b375b39c8323ea26ccbb67135fcd Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Tue, 6 Jun 2023 15:01:31 +0200 Subject: Inverted both "Précédent" and "Suivant" --- packages/starlight/translations/fr.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/starlight/translations/fr.json b/packages/starlight/translations/fr.json index 91be0788..55a69fee 100644 --- a/packages/starlight/translations/fr.json +++ b/packages/starlight/translations/fr.json @@ -15,6 +15,6 @@ "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", "page.editLink": "Editer la page", "page.lastUpdated": "Dernière mise à jour :", - "page.previousLink": "Suivant", - "page.nextLink": "Précédent" - } \ No newline at end of file + "page.previousLink": "Précédent", + "page.nextLink": "Suivant" + } -- cgit From 6a05bfde0bc69eb6925f8d332d5fd6a0f67d9ad8 Mon Sep 17 00:00:00 2001 From: Thomas Bnt Date: Tue, 6 Jun 2023 15:02:35 +0200 Subject: Inverted both "Précédent" and "Suivant" --- docs/src/content/docs/fr/guides/i18n.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/fr/guides/i18n.mdx b/docs/src/content/docs/fr/guides/i18n.mdx index a5bb7715..19c5d6f6 100644 --- a/docs/src/content/docs/fr/guides/i18n.mdx +++ b/docs/src/content/docs/fr/guides/i18n.mdx @@ -195,7 +195,7 @@ Vous pouvez fournir des traductions pour les langues supplémentaires que vous s "i18n.untranslatedContent": "Ce contenu n'est pas encore disponible dans votre langue.", "page.editLink": "Editer la page", "page.lastUpdated": "Dernière mise à jour :", - "page.previousLink": "Suivant", - "page.nextLink": "Précédent" + "page.previousLink": "Précédent", + "page.nextLink": "Suivant" } ``` -- cgit From 823be91faca6545df41299589346df6c6d637bf5 Mon Sep 17 00:00:00 2001 From: Waxer59 Date: Tue, 6 Jun 2023 15:07:21 +0200 Subject: i18n(es): Updated `configuration.md` (#145) Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>--- docs/src/content/docs/es/reference/configuration.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/src/content/docs/es/reference/configuration.md b/docs/src/content/docs/es/reference/configuration.md index 7761ee63..a19075fb 100644 --- a/docs/src/content/docs/es/reference/configuration.md +++ b/docs/src/content/docs/es/reference/configuration.md @@ -5,6 +5,21 @@ description: Una descripción general de todas las opciones de configuración qu ## Configurar la integración `starlight` +Starlight es una integración construida sobre el framework [Astro](https://astro.build). Puedes configurar tu proyecto dentro del archivo de configuración de Astro `astro.config.mjs`: + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; +export default defineConfig({ + integrations: [ + starlight({ + title: "My delightful docs site", + }), + ], +}); +``` + Puedes pasar las siguientes opciones a la integración `starlight`. ### `title` (requerido) -- cgit From 040baec380bdc7a181acdc3abe6a1e1ade73b7d9 Mon Sep 17 00:00:00 2001 From: Marc Date: Tue, 6 Jun 2023 15:11:15 +0200 Subject: i18n(de): update configuration.md (#152) Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>--- docs/src/content/docs/de/reference/configuration.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/de/reference/configuration.md b/docs/src/content/docs/de/reference/configuration.md index 015acc6a..b4aef5e3 100644 --- a/docs/src/content/docs/de/reference/configuration.md +++ b/docs/src/content/docs/de/reference/configuration.md @@ -3,9 +3,25 @@ title: Konfigurations­referenz description: Ein Überblick über alle von Starlight unterstützten Konfigurationsoptionen. --- -## Die Starlight-Integration konfigurieren +## Konfiguriere die `starlight` Integration -Du kannst die folgenden Optionen an die Starlight-Integration übergeben. +Starlight ist eine Integration, die auf dem [Astro](https://astro.build) Web-Framework aufbaut. Du kannst dein Projekt innerhalb der Astro-Konfigurationsdatei `astro.config.mjs` anpassen: + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: "My delightful docs site", + }), + ], +}); +``` + +Du kannst die folgenden Optionen an die `starlight` Integration übergeben. ### `title` (erforderlich) -- cgit