Merge branch 'main' into i18n-ja-project-structure-0

7 files changed, 149 insertions, 175 deletions

diff --git a/.changeset/angry-dragons-flash.md b/.changeset/angry-dragons-flash.md
new file mode 100644
index 00000000..d617e045
--- /dev/null
+++ b/.changeset/angry-dragons-flash.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Release v0.1.0
diff --git a/docs/src/content/docs/reference/markdown-syntax.md b/docs/src/content/docs/guides/authoring-content.md
index 922d2ce5..bfeb044e 100644
--- a/docs/src/content/docs/reference/markdown-syntax.md
+++ b/docs/src/content/docs/guides/authoring-content.md
@@ -1,9 +1,11 @@
 ---
-title: Markdown Syntax
+title: Authoring Content in Markdown
 description: An overview of the Markdown syntax Starlight supports.
 ---
 
-Starlight supports the full range of Markdown syntax.
+Starlight supports the full range of [Markdown](https://daringfireball.net/projects/markdown/) syntax in `.md` files as well as frontmatter [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) to define metadata such as a title and description. 
+
+Please be sure to check the [MDX docs](https://mdxjs.com/docs/what-is-mdx/#markdown) or [Markdoc docs](https://markdoc.dev/docs/syntax) if using those file formats, as Markdown support and usage can differ.
 
 ## Inline styles
 
@@ -13,10 +15,10 @@ Text can be **bold**, _italic_, or ~~strikethrough~~.
 Text can be **bold**, _italic_, or ~~strikethrough~~.
 ```
 
-You can [link to another page](/getting-started.md).
+You can [link to another page](/getting-started/).
 
 ```md
-You can [link to another page](/getting-started.md).
+You can [link to another page](/getting-started/).
 ```
 
 You can highlight `inline code` with backticks.
@@ -25,37 +27,74 @@ You can highlight `inline code` with backticks.
 You can highlight `inline code` with backticks.
 ```
 
-## Headings
+## Images
+
+Images in Starlight use Astro's built-in optimized asset support.
+
+Markdown and MDX support the Markdown syntax for displaying images that includes alt-text for screen readers and assistive technology.
+
+![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)
+
+```md
+![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)
+```
+
+Relative image paths are also supported for images stored locally in your project.
 
-You can structure content using a heading. Headings in Markdown are indicated by a number of `#` at the start of the line. Although it is supported, you should should generally avoid top-level headings and start on-page headings from `<h2>` and down.
+```md
+// src/content/docs/page-1.md
+
+![A rocketship in space.](../../assets/images/rocket.svg)
+```
 
-## Heading 2
 
-### Heading 3
+## Headings
 
-#### Heading 4
+You can structure content using a heading. Headings in Markdown are indicated by a number of `#` at the start of the line. 
 
-##### Heading 5
+### How to structure page content in Starlight
 
-###### Heading 6
+Starlight is configured to automatically use your page title as a top-level heading and will include an "Overview" heading at top of each page's table of contents. We recommend starting each page with regular paragraph text content and using on-page headings from `<h2>` and down:
 
 ```md
-## Heading 2
+---
+title: Markdown Guide
+description: How to use Markdown in Starlight
+---
+
+This page describes how to use Markdown in Starlight.
+
+## Inline Styles
 
-### Heading 3
+## Headings
+
+```
+
+### Automatic heading anchor links
+
+Using headings in Markdown will automatically give you anchor links so you can link directly to certain sections of your page:
 
-#### Heading 4
+```md
+---
+title: My page of content
+description: How to use Starlight's built-in anchor links
+---
+## Introduction
 
-##### Heading 5
+I can link to [my conclusion](#conclusion) lower on the same page.
 
-###### Heading 6
+## Conclusion
+
+`https://my-site.com/page1/#introduction` navigates directly to my Introduction. 
 ```
+Level 2 (`<h2>`) and Level 3 (`<h3>`) headings will automatically appear in the page table of contents.
+
 
 ## Asides
 
 Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content.
 
-Starlight provides a custom Markdown syntax for rendering asides. Aside blocks are indicated using a triple colon `:::` and can be of type `note`, `tip`, `caution` or `danger`.
+Starlight provides a custom Markdown syntax for rendering asides. Aside blocks are indicated using a pair of triple colons `:::` to wrap your content, and can be of type `note`, `tip`, `caution` or `danger`.
 
 You can nest any other Markdown content types inside an aside, but asides are best suited to short and concise chunks of content.
 
@@ -166,132 +205,7 @@ var fun = function lang(l) {
 Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
 ```
 
-## Lists
-
-Markdown supports unordered lists (often call “bullet” lists) and ordered lists, which are numbered sequentially.
-
-### Here is an unordered list:
-
-- Item foo
-- Item bar
-- Item baz
-
-### And an ordered list:
-
-1.  Item one
-1.  Item two
-1.  Item three
-
-### And some nested lists
-
-- level 1 item (ul)
-  1. level 2 item (ol)
-  1. level 2 item (ol)
-     - level 3 item (ul)
-     - level 3 item (ul)
-- level 1 item (ul)
-  1. level 2 item (ol)
-  1. level 2 item (ol)
-     - level 3 item (ul)
-     - level 3 item (ul)
-       1. level 4 item (ol)
-       1. level 4 item (ol)
-     - level 3 item (ul)
-     - level 3 item (ul)
-- level 1 item (ul)
-
-### Nesting mixed content in lists
-
-- This list contains code samples
-
-  ```js
-  console.log('hi');
-  ```
-
-- And **other** content such as images:
-  ![VuePress logo](https://raw.githubusercontent.com/withastro/docs/main/public/logos/vuepress.png)
-
-- or blockquotes
-
-  > to dent
-
-- But inline styling like **bold**, _italic_, `code`, or ~~strikethrough~~, do not change vertical spacing.
-
-- Right?
-
-## Tables
-
-Markdown tables support horizontal alignment.
-
-| head1        |     head two      | three |
-| :----------- | :---------------: | ----: |
-| ok           | good swedish fish |  nice |
-| out of stock |  good and plenty  |  nice |
-| ok           |   good `oreos`    |   hmm |
-| ok           | good `zoute` drop |  yumm |
-
-```md
-| head1        |     head two      | three |
-| :----------- | :---------------: | ----: |
-| ok           | good swedish fish |  nice |
-| out of stock |  good and plenty  |  nice |
-| ok           |   good `oreos`    |   hmm |
-| ok           | good `zoute` drop |  yumm |
-```
-
-## Horizontal rules
-
-Markdown supports rendering a horizontal rule (an `<hr>` element) with a triple-dash syntax: `---`.
-
----
-
-```md
----
-```
-
-## Definition lists
-
-While Markdown doesn’t provide a custom syntax for definition lists, you can still write them using the standard HTML `<dl>`, `<dt>`, and `<dd>` elements:
-
-<dl>
-  <dt>Name</dt>
-  <dd>Godzilla</dd>
-  <dt>Born</dt>
-  <dd>1952</dd>
-  <dt>Term 1</dt>
-  <dt>Term 2</dt>
-  <dd>First description of Term1 and Term2, possibly more than one line</dd>
-  <dd>Second description of Term1 and Term2, possibly more than one line</dd>
-</dl>
-
-## Images
-
-### Small image
-
-![VuePress logo](https://raw.githubusercontent.com/withastro/docs/main/public/logos/vuepress.png)
-
-```md
-![VuePress logo](https://raw.githubusercontent.com/withastro/docs/main/public/logos/vuepress.png)
-```
-
-### Large image
-
-![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)
-
-```md
-![An illustration of planets and stars featuring the word “astro”](https://raw.githubusercontent.com/withastro/docs/main/public/default-og-image.png)
-```
-
-## Miscellaneous markup tests
-
-### Long links test
-
-[This is a very long link which wraps and therefore doesn't overflow
-even when it comes at the beginning](.) of the line.
-
-- [This is a very long link which wraps and therefore doesn't overflow the line
-  when used first in an item ](.) in a list.
+## Other common Markdown features
 
-### Supercalifragilisticexpialidocious!
+Starlight supports all other Markdown authoring syntax, such as lists and tables. See the [Markdown Cheat Sheet from The Markdown Guide](https://www.markdownguide.org/cheat-sheet/) for a quick overview of all the Markdown syntax elements.
 
-Making sure that this heading with a very long word in wraps instead of overflowing on small screens.
diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx
index c991664f..54978517 100644
--- a/docs/src/content/docs/guides/components.mdx
+++ b/docs/src/content/docs/guides/components.mdx
@@ -3,13 +3,15 @@ title: Components
 description: Using components in MDX with Starlight.
 ---
 
-Components let you easily re-use a piece of UI or styling consistently.
+Components let you easily reuse a piece of UI or styling consistently.
 Examples might include a link card or a YouTube embed.
 Starlight supports the use of components in [MDX](https://mdxjs.com/) files and provides some common components for you to use.
 
+[Learn more about building components in the Astro Docs](https://docs.astro.build/en/core-concepts/astro-components/).
+
 ## Using a component
 
-You can use a component by importing it into your MDX file and then calling it as a JSX tag.
+You can use a component by importing it into your MDX file and then rendering it as a JSX tag.
 These look like HTML tags but start with an uppercase letter matching the name in your `import` statement:
 
 ```mdx
@@ -28,12 +30,12 @@ import AnotherComponent from '../../components/AnotherComponent.astro';
 </AnotherComponent>
 ```
 
-Because Starlight is powered by Astro, you can use components built with any UI framework in your MDX files.
+Because Starlight is powered by Astro, you can add support for components built with any [supported UI framework (React, Preact, Svelte, Vue, Solid, Lit, and Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) in your MDX files.
 Learn more about [using components in MDX](https://docs.astro.build/en/guides/markdown-content/#using-components-in-mdx) in the Astro docs.
 
 ## Built-in components
 
-Starlight provides built-in components for common documentation use cases.
+Starlight provides some built-in components for common documentation use cases.
 These components are available from the `@astrojs/starlight/components` package.
 
 ### Tabs
@@ -66,7 +68,7 @@ import { Card, CardGrid } from '@astrojs/starlight/components';
 You can display content in a box matching Starlight’s styles using the `<Card>` component.
 Wrap multiple cards in the `<CardGrid>` component to display cards side-by-side when there’s enough space.
 
-A `<Card>` should have a `title` and can optionally include an `icon` attribute set to the name of [one of Starlight’s built-in icons](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts).
+A `<Card>` requires a `title` and can optionally include an `icon` attribute set to the name of [one of Starlight’s built-in icons](https://github.com/withastro/starlight/blob/main/packages/starlight/components/Icons.ts).
 
 ```mdx
 import { Card, CardGrid } from '@astrojs/starlight/components';
diff --git a/docs/src/content/docs/guides/i18n.mdx b/docs/src/content/docs/guides/i18n.mdx
index f59890bc..90dea6a7 100644
--- a/docs/src/content/docs/guides/i18n.mdx
+++ b/docs/src/content/docs/guides/i18n.mdx
@@ -46,7 +46,7 @@ Starlight provides built-in support for multilingual sites, including routing, f
    Your `defaultLocale` will be used for fallback content and UI labels, so choose the language you are most likely to start writing content in, or already have content for.
 
 2. Create a directory for each language in `src/content/docs/`.
-   For example, assuming the configuration shown in step 1, this might look like:
+   For example, for the configuration shown above, create the following folders:
 
    <FileTree>
 
@@ -59,11 +59,13 @@ Starlight provides built-in support for multilingual sites, including routing, f
 
    </FileTree>
 
-3. You can now create content files in your language directories. Use the same file name to tie pages together across languages. For example, `ar/index.md` and `en/index.md` would represent the homepage for Arabic and English respectively.
+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.
 
 ### Use a root locale
 
-You can use a “root” locale to serve a language without any i18n prefix in its path. For example, if English is your root locale, an English page path might look like `/about` instead of `/en/about`.
+You can use a “root” locale to serve a language without any i18n prefix in its path. For example, if English is your root locale, an English page path would look like `/about` instead of `/en/about`.
 
 To set a root locale, use the `root` key in your `locales` config. If the root locale is also the default locale for your content, remove `defaultLocale` or set it to `'root'`.
 
@@ -92,7 +94,7 @@ export default defineConfig({
 });
 ```
 
-When using a `root` locale, place pages for that language directly in `src/content/docs/` instead of in a dedicated language folder. For example, here are the home page files for English and Chinese when using the config above:
+When using a `root` locale, keep pages for that language directly in `src/content/docs/` instead of in a dedicated language folder. For example, here are the home page files for English and Chinese when using the config above:
 
 <FileTree>
 
@@ -107,26 +109,48 @@ When using a `root` locale, place pages for that language directly in `src/conte
 
 #### Monolingual sites
 
-If you have a single language site, you can set the root locale to configure its language.
-This allows you to override Starlight’s default language, which is English, but won’t enable other internationalization features like the language picker.
+By default, Starlight is a monolingual (English) site. To create a single language site in another language, set it as the `root` in your `locales` config:
+
+```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',
+        },
+      },
+    }),
+  ],
+});
+```
+
+This allows you to override Starlight’s default language without enabling other internationalization features for multi-language sites, such as the language picker.
 
 ## Fallback content
 
-Starlight expects you to create equivalent pages in all your languages. For example, if you have an `en/about.md` file, you should create an `about.md` for each other language you support.
+Starlight expects you to create equivalent pages in all your languages. For example, if you have an `en/about.md` file, create an `about.md` for each other language you support. This allows Starlight to provide automatic fallback content for pages that have not yet been translated.
+
+If a translation is not yet available for a language, Starlight will show readers the content for that page in the default language (set via `defaultLocale`). For example, if you have not yet created a French version of your About page and your default language is English, visitors to `/fr/about` will see the English content from `/en/about` with a notice that this page has not yet been translated. This helps you add content in your default language and then progressively translate it when your translators have time.
 
-If a translation is not yet available for a language, Starlight will show readers the content for that page in the default language (set via `defaultLocale`). For example, if you have not yet created a French version of an about page and your default language is English, visitors to `/fr/about` will see the English content. This helps you add content in your default language and then progressively translate it when your translators have time.
+## Translate Starlight's UI
 
-## Translate Starlight’s UI
+In addition to hosting translated content files, Starlight allows you to translate the default UI strings (e.g. the "On this page" heading in the table of contents) so that your readers can experience your site entirely in the selected language. 
 
-Some of Starlight’s default UI requires text labels to work.
-For example, the table of contents on this page has an “On this page” heading in English.
-We aim to ship these labels in as many languages as possible. Currently, English, German, Japanese, Portuguese, and Spanish are supported out of the box.
+English, German, Japanese, Portuguese, and Spanish translated UI strings are provided out of the box, and we welcome [contributions to add more default languages](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).
 
 You can provide translations for additional languages you support — or override our default labels — via the `i18n` data collection.
 
 1. Configure the `i18n` data collection in `src/content/config.ts` if it isn’t configured already:
 
    ```js
+   // src/content/config.ts
    import { defineCollection } from 'astro:content';
    import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 
@@ -136,7 +160,7 @@ You can provide translations for additional languages you support — or overrid
    };
    ```
 
-2. Create a JSON file in `src/content/i18n/` for each locale you want to translate Starlight’s UI for.
+2. Create a JSON file in `src/content/i18n/` for each additional locale you want to provide UI translation strings for.
    For example, this would add translation files for Arabic and Simplified Chinese:
 
    <FileTree>
@@ -149,7 +173,9 @@ You can provide translations for additional languages you support — or overrid
 
    </FileTree>
 
-3. Add translations for the keys you want to translate to the JSON files. You can use the English defaults to help you translate:
+3. Add translations for the keys you want to translate to the JSON files. Translate only the values, leaving the keys in English (e.g. `"search.label": "Buscar"`). 
+
+    These are the English defaults of the existing strings Starlight ships with:
 
    ```json
    {
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の新しいプロジェクトを作成できます。
 
 <Tabs>
 <TabItem label="npm">
@@ -40,7 +42,7 @@ yarn create astro --template starlight
 </TabItem>
 </Tabs>
 
-これにより、サイトに必要なすべてのファイルと設定が含まれた、新しいプロジェクトディレクトリが作成されます。
+これにより、サイトに必要なすべてのファイルと設定が含まれた、新しい[プロジェクトディレクトリ](/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/)
diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
index aafacf99..88db44cf 100644
--- a/docs/src/content/docs/reference/configuration.md
+++ b/docs/src/content/docs/reference/configuration.md
@@ -5,6 +5,22 @@ description: An overview of all the configuration options Starlight supports.
 
 ## Configure the `starlight` integration
 
+Starlight is an integration built on top the [Astro](https://astro.build) web framework. You can configure your project inside the Astro `astro.config.mjs` configuration file:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: "My delightful docs site",
+    }),
+  ],
+});
+```
+
 You can pass the following options to the `starlight` integration.
 
 ### `title` (required)
diff --git a/examples/basics/astro.config.mjs b/examples/basics/astro.config.mjs
index b3e86d36..bd23e21f 100644
--- a/examples/basics/astro.config.mjs
+++ b/examples/basics/astro.config.mjs
@@ -11,17 +11,13 @@ export default defineConfig({
       },
       sidebar: [
         {
-          label: 'Start Here',
+          label: 'Guides',
           items: [
             // Each item here is one entry in the navigation menu.
-            { label: 'Getting Started', link: '/' },
+            { label: 'Example Guide', link: '/guides/example/' },
           ],
         },
         {
-          label: 'Guides',
-          autogenerate: { directory: 'guides' },
-        },
-        {
           label: 'Reference',
           autogenerate: { directory: 'reference' },
         },