From 65102e66fbdac2bc01977c80414b6b3c96683774 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 00:11:02 +0000 Subject: edits to guides --- docs/src/content/docs/guides/components.mdx | 16 +++++---- docs/src/content/docs/guides/i18n.mdx | 54 +++++++++++++++++++++-------- 2 files changed, 49 insertions(+), 21 deletions(-) diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index c991664f..1915bee4 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'; ``` -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 also can use 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 @@ -63,10 +65,10 @@ The code above generates the following tabs on the page: import { Card, CardGrid } from '@astrojs/starlight/components'; -You can display content in a box matching Starlight’s styles using the `` component. +You can display content in a box matching Starlight's styles using the `` component. Wrap multiple cards in the `` component to display cards side-by-side when there’s enough space. -A `` 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 `` 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'; @@ -97,7 +99,7 @@ The code above generates the following on the page: :::tip -Use a card grid on your home page to display your project’s key features. +Use a card grid on your home page to display your project's key features. Add the `stagger` attribute to shift the second column of cards vertically and add visual interest: ```astro diff --git a/docs/src/content/docs/guides/i18n.mdx b/docs/src/content/docs/guides/i18n.mdx index f59890bc..3a1734c1 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: @@ -59,11 +59,13 @@ Starlight provides built-in support for multilingual sites, including routing, f -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 together 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: @@ -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: @@ -149,7 +173,9 @@ You can provide translations for additional languages you support — or overrid -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 { -- cgit From bcffab6897fadbb5b73648e36d7a7726f2b3b440 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Mon, 5 Jun 2023 02:39:26 +0200 Subject: Apostrophes --- docs/src/content/docs/guides/components.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index 1915bee4..62060c09 100644 --- a/docs/src/content/docs/guides/components.mdx +++ b/docs/src/content/docs/guides/components.mdx @@ -65,7 +65,7 @@ The code above generates the following tabs on the page: import { Card, CardGrid } from '@astrojs/starlight/components'; -You can display content in a box matching Starlight's styles using the `` component. +You can display content in a box matching Starlight’s styles using the `` component. Wrap multiple cards in the `` component to display cards side-by-side when there’s enough space. A `` 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). @@ -99,7 +99,7 @@ The code above generates the following on the page: :::tip -Use a card grid on your home page to display your project's key features. +Use a card grid on your home page to display your project’s key features. Add the `stagger` attribute to shift the second column of cards vertically and add visual interest: ```astro -- cgit From 3b5aa55e6c1c6d611cdf44c1dfc9dbdc99c6bd67 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Mon, 5 Jun 2023 02:40:49 +0200 Subject: remove leading slash from file name --- 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 3a1734c1..29a9149f 100644 --- a/docs/src/content/docs/guides/i18n.mdx +++ b/docs/src/content/docs/guides/i18n.mdx @@ -135,7 +135,7 @@ This allows you to override Starlight’s default language without enabling othe ## Fallback content -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. +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. -- cgit From dae9b008abdec24fa6231fdb549262063f5a675d Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 01:11:34 +0000 Subject: authoring content guide - nwtwwhb --- docs/src/content/docs/guides/authoring-content.md | 201 ++++++++++++++ docs/src/content/docs/reference/markdown-syntax.md | 297 --------------------- 2 files changed, 201 insertions(+), 297 deletions(-) create mode 100644 docs/src/content/docs/guides/authoring-content.md delete mode 100644 docs/src/content/docs/reference/markdown-syntax.md diff --git a/docs/src/content/docs/guides/authoring-content.md b/docs/src/content/docs/guides/authoring-content.md new file mode 100644 index 00000000..aa6e6598 --- /dev/null +++ b/docs/src/content/docs/guides/authoring-content.md @@ -0,0 +1,201 @@ +--- +title: Authoring Content in Markdown +description: An overview of the Markdown syntax Starlight supports. +--- + +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 + +Text can be **bold**, _italic_, or ~~strikethrough~~. + +```md +Text can be **bold**, _italic_, or ~~strikethrough~~. +``` + +You can [link to another page](/getting-started/). + +```md +You can [link to another page](/getting-started/). +``` + +You can highlight `inline code` with backticks. + +```md +You can highlight `inline code` with backticks. +``` + +## Images + +Markdown supports 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) +``` + + +## Headings + +You can structure content using a heading. Headings in Markdown are indicated by a number of `#` at the start of the line. + +### How to structure page content in Starlight + +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 `

` and down: + +```md +--- +title: Markdown Guide +description: How to use Markdown in Starlight +--- + +This page describes how to use Markdown in Starlight. + +## Inline Styles + +## 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: + +```md +--- +title: My page of content +description: How to use Starlight's built-in anchor links +--- +## Introduction + +I can link to [my conclusion](#conclusion) lower on the same page. + +## Conclusion + +`https://my-site.com/page1/#introduction` navigates directly to my Introduction. +``` +Level 2 (`

`) and Level 3 (`

`) 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 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. + +### Note aside + +:::note +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 +``` + +::: + +````md +:::note +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 +``` + +::: +```` + +### Custom aside titles + +You can specify a custom title for the aside in square brackets following the aside type, e.g. `:::tip[Did you know?]`. + +:::tip[Did you know?] +Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). +::: + +```md +:::tip[Did you know?] +Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). +::: +``` + +### More aside types + +Caution and danger asides are helpful for drawing a user’s attention to details that may trip them up. +If you find yourself using these a lot, it may also be a sign that the thing you are documenting could benefit from being redesigned. + +:::caution +If you are not sure you want an awesome docs site, think twice before using [Starlight](../../). +::: + +:::danger +Your users may be more productive and find your product easier to use thanks to helpful Starlight features. + +- Clear navigation +- User-configurable colour theme +- [i18n support](/guides/i18n) + +::: + +```md +:::caution +If you are not sure you want an awesome docs site, think twice before using [Starlight](../../). +::: + +:::danger +Your users may be more productive and find your product easier to use thanks to helpful Starlight features. + +- Clear navigation +- User-configurable colour theme +- [i18n support](/guides/i18n) + +::: +``` + +## Blockquotes + +> This is a blockquote, which is commonly used when quoting another person or document. +> +> Blockquotes are indicated by a `>` at the start of each line. + +```md +> This is a blockquote, which is commonly used when quoting another person or document. +> +> Blockquotes are indicated by a `>` at the start of each line. +``` + +## Code blocks + +A code block is indicated by a block with three backticks ``` at the start and end. You can indicate the programming language being used after the opening backticks. + +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` + +````md +```js +// Javascript code with syntax highlighting. +var fun = function lang(l) { + dateformat.i18n = require('./lang/' + l); + return true; +}; +``` +```` + +```md +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. +``` + +## Other common Markdown features + +Starlight supports all other common Markdown authoring syntax, such as lists and tables. See the [Markdown documentation](https://daringfireball.net/projects/markdown/) for all the options available. + diff --git a/docs/src/content/docs/reference/markdown-syntax.md b/docs/src/content/docs/reference/markdown-syntax.md deleted file mode 100644 index 922d2ce5..00000000 --- a/docs/src/content/docs/reference/markdown-syntax.md +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: Markdown Syntax -description: An overview of the Markdown syntax Starlight supports. ---- - -Starlight supports the full range of Markdown syntax. - -## Inline styles - -Text can be **bold**, _italic_, or ~~strikethrough~~. - -```md -Text can be **bold**, _italic_, or ~~strikethrough~~. -``` - -You can [link to another page](/getting-started.md). - -```md -You can [link to another page](/getting-started.md). -``` - -You can highlight `inline code` with backticks. - -```md -You can highlight `inline code` with backticks. -``` - -## Headings - -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 `

` and down. - -## Heading 2 - -### Heading 3 - -#### Heading 4 - -##### Heading 5 - -###### Heading 6 - -```md -## Heading 2 - -### Heading 3 - -#### Heading 4 - -##### Heading 5 - -###### Heading 6 -``` - -## 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`. - -You can nest any other Markdown content types inside an aside, but asides are best suited to short and concise chunks of content. - -### Note aside - -:::note -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 -``` - -::: - -````md -:::note -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 -``` - -::: -```` - -### Custom aside titles - -You can specify a custom title for the aside in square brackets following the aside type, e.g. `:::tip[Did you know?]`. - -:::tip[Did you know?] -Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). -::: - -```md -:::tip[Did you know?] -Astro helps you build faster websites with [“Islands Architecture”](https://docs.astro.build/en/concepts/islands/). -::: -``` - -### More aside types - -Caution and danger asides are helpful for drawing a user’s attention to details that may trip them up. -If you find yourself using these a lot, it may also be a sign that the thing you are documenting could benefit from being redesigned. - -:::caution -If you are not sure you want an awesome docs site, think twice before using [Starlight](../../). -::: - -:::danger -Your users may be more productive and find your product easier to use thanks to helpful Starlight features. - -- Clear navigation -- User-configurable colour theme -- [i18n support](/guides/i18n) - -::: - -```md -:::caution -If you are not sure you want an awesome docs site, think twice before using [Starlight](../../). -::: - -:::danger -Your users may be more productive and find your product easier to use thanks to helpful Starlight features. - -- Clear navigation -- User-configurable colour theme -- [i18n support](/guides/i18n) - -::: -``` - -## Blockquotes - -> This is a blockquote, which is commonly used when quoting another person or document. -> -> Blockquotes are indicated by a `>` at the start of each line. - -```md -> This is a blockquote, which is commonly used when quoting another person or document. -> -> Blockquotes are indicated by a `>` at the start of each line. -``` - -## Code blocks - -A code block is indicated by a block with three backticks ``` at the start and end. You can indicate the programming language being used after the opening backticks. - -```js -// Javascript code with syntax highlighting. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` - -````md -```js -// Javascript code with syntax highlighting. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l); - return true; -}; -``` -```` - -```md -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 `
` 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 `
`, `
`, and `
` elements: - -
-
Name
-
Godzilla
-
Born
-
1952
-
Term 1
-
Term 2
-
First description of Term1 and Term2, possibly more than one line
-
Second description of Term1 and Term2, possibly more than one line
-
- -## 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. - -### Supercalifragilisticexpialidocious! - -Making sure that this heading with a very long word in wraps instead of overflowing on small screens. -- cgit 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 5d3dae9f647f62aeffdb78a262f309718404ff4e Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Mon, 5 Jun 2023 10:55:54 +0200 Subject: Remove “Start Here” sidebar section in starter template --- examples/basics/astro.config.mjs | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) 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,16 +11,12 @@ 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' }, -- cgit From 43f3a024d6903072780f158dd95fb04b9f678535 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Mon, 5 Jun 2023 10:57:27 +0200 Subject: Add 0.1.0 changeset --- .changeset/angry-dragons-flash.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/angry-dragons-flash.md 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 -- cgit From 262f4846e9d54c00e4a6151df909684c1f7cdd07 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 06:11:48 -0300 Subject: we're NOT in this together Co-authored-by: Chris Swithinbank --- 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 29a9149f..90dea6a7 100644 --- a/docs/src/content/docs/guides/i18n.mdx +++ b/docs/src/content/docs/guides/i18n.mdx @@ -59,7 +59,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 together across languages and take advantage of Starlight’s full set of i18n features, including fallback content, translation notices, and more. +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. -- cgit From 93d14db20ea564ec1af5321cb6b06c4ec0a49d77 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 06:12:23 -0300 Subject: add support for framework components Co-authored-by: Chris Swithinbank --- docs/src/content/docs/guides/components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx index 62060c09..54978517 100644 --- a/docs/src/content/docs/guides/components.mdx +++ b/docs/src/content/docs/guides/components.mdx @@ -30,7 +30,7 @@ import AnotherComponent from '../../components/AnotherComponent.astro'; ``` -Because Starlight is powered by Astro, you also can use 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. +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 -- cgit From b9363b15e1fbcdf5e24774c917a40f0353254863 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 09:32:31 +0000 Subject: config reference intro and example --- docs/src/content/docs/reference/configuration.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md index aafacf99..483bb5a1 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 [Astro integration](https://docs.astro.build/en/guides/integrations-guide/), configured in `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", + }), + ], +}); +``` + You can pass the following options to the `starlight` integration. ### `title` (required) -- cgit From f8e119373a898776a3ac2edc9955288f084cfe77 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 06:45:58 -0300 Subject: less overwhelming! Co-authored-by: Fred K. Schott --- docs/src/content/docs/reference/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md index 483bb5a1..88db44cf 100644 --- a/docs/src/content/docs/reference/configuration.md +++ b/docs/src/content/docs/reference/configuration.md @@ -5,7 +5,7 @@ description: An overview of all the configuration options Starlight supports. ## Configure the `starlight` integration -Starlight is an [Astro integration](https://docs.astro.build/en/guides/integrations-guide/), configured in `astro.config.mjs`. +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 -- cgit From 385e61746b516de6c8ea2baed2d906c1fea8621d Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 07:02:01 -0300 Subject: more helpful Markdown link to guide --- docs/src/content/docs/guides/authoring-content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/authoring-content.md b/docs/src/content/docs/guides/authoring-content.md index aa6e6598..b2dbc316 100644 --- a/docs/src/content/docs/guides/authoring-content.md +++ b/docs/src/content/docs/guides/authoring-content.md @@ -197,5 +197,5 @@ Long, single-line code blocks should not wrap. They should horizontally scroll i ## Other common Markdown features -Starlight supports all other common Markdown authoring syntax, such as lists and tables. See the [Markdown documentation](https://daringfireball.net/projects/markdown/) for all the options available. +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. -- cgit From fd5d95c7dbedafb6273018a4d7adb153541738a3 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 07:04:29 -0300 Subject: errant syntax error fix --- docs/src/content/docs/guides/authoring-content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/authoring-content.md b/docs/src/content/docs/guides/authoring-content.md index b2dbc316..074a7ed7 100644 --- a/docs/src/content/docs/guides/authoring-content.md +++ b/docs/src/content/docs/guides/authoring-content.md @@ -197,5 +197,5 @@ Long, single-line code blocks should not wrap. They should horizontally scroll i ## Other common Markdown features -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. +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. -- cgit From 6ca10a3a66f582d0f4bd0e801a6223ec316bd458 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 5 Jun 2023 10:25:55 +0000 Subject: relative image example --- docs/src/content/docs/guides/authoring-content.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/guides/authoring-content.md b/docs/src/content/docs/guides/authoring-content.md index 074a7ed7..bfeb044e 100644 --- a/docs/src/content/docs/guides/authoring-content.md +++ b/docs/src/content/docs/guides/authoring-content.md @@ -29,7 +29,9 @@ You can highlight `inline code` with backticks. ## Images -Markdown supports syntax for displaying images that includes alt-text for screen readers and assistive technology. +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) @@ -37,6 +39,14 @@ Markdown supports syntax for displaying images that includes alt-text for screen ![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. + +```md +// src/content/docs/page-1.md + +![A rocketship in space.](../../assets/images/rocket.svg) +``` + ## Headings -- cgit