From b69aaacbcb12f71f36a49daa56c647ea1fa31ab8 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Thu, 2 Nov 2023 13:57:31 +0100 Subject: [PATCH 1/4] Overhaul getting started guide --- docs/src/content/docs/getting-started.mdx | 87 +++++++++++++++-------- 1 file changed, 59 insertions(+), 28 deletions(-) diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index 827fc08621..e0112d54a7 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -5,17 +5,19 @@ description: Learn how to start building your next documentation site with Starl import { Tabs, TabItem } from '@astrojs/starlight/components'; -## Creating a new project - Starlight is a full-featured documentation theme built on top of the [Astro](https://astro.build) framework. +This guide will help you get started with a new project. + +## Quick Start -You can create a new Astro + Starlight project using the following command: +### Create a new project + +Create a new Astro + Starlight project by running the following command in your terminal: ```sh -# create a new project with npm npm create astro@latest -- --template starlight ``` @@ -23,7 +25,6 @@ npm create astro@latest -- --template starlight ```sh -# create a new project with pnpm pnpm create astro --template starlight ``` @@ -31,7 +32,6 @@ pnpm create astro --template starlight ```sh -# create a new project with yarn yarn create astro --template starlight ``` @@ -45,24 +45,56 @@ Try Starlight in your browser: [open the template on StackBlitz](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics). ::: -## Creating content with Starlight +### Start the development server -Starlight is ready for you to add new content, or bring your existing files! +When working locally, [Astro’s development server](https://docs.astro.build/en/reference/cli-reference/#astro-dev) lets you preview your work and automatically refreshes your browser when you make changes. -### File formats +Inside your project directory, run the following command to start the development server: -Starlight supports authoring content in Markdown and MDX. (You can add support for Markdoc by installing the experimental [Astro Markdoc integration](https://docs.astro.build/en/guides/integrations-guide/markdoc/).) + + -### Add pages +```sh +npm run dev +``` -Add new pages to your site automatically by creating `.md` or `.mdx` files in `src/content/docs/`. Add sub-folders to organize your files, and to create multiple path segments: + + +```sh +pnpm dev ``` -src/content/docs/hello-world.md => your-site.com/hello-world -src/content/docs/guides/faq.md => your-site.com/guides/faq + + + + +```sh +yarn dev ``` -### Type-safe frontmatter + + + +This will log a message to your terminal with the URL of your local preview. +Open this URL to start browsing your site. + +### Add content + +Starlight is ready for you to add new content, or bring your existing files! + +#### File formats + +Starlight supports authoring content in Markdown and MDX with no configuration required. +You can add support for Markdoc by installing the experimental [Astro Markdoc integration](https://docs.astro.build/en/guides/integrations-guide/markdoc/). + +#### Add pages + +Add new pages to your site by creating `.md` or `.mdx` files in `src/content/docs/`. +Use sub-folders to organize your files and to create multiple path segments. + +For example, a file at `src/content/docs/hello-world.md` will be published at `your-site.com/hello-world` and a file at `src/content/docs/guides/faq.md` will be published at `your-site.com/guides/faq`. + +#### Type-safe frontmatter All Starlight pages share a customizable [common set of frontmatter properties](/reference/frontmatter/) to control how the page appears: @@ -75,16 +107,18 @@ description: This is a page in my Starlight-powered site If you forget anything important, Starlight will let you know. -## Deploying your Starlight website - -Once you have created and customized your Starlight website, you can deploy it to a web server or hosting platform of your choice including Netlify, Vercel, GitHub Pages and many more. +### Next steps -[Learn about deploying an Astro site in the Astro docs.](https://docs.astro.build/en/guides/deploy/) +- **Configure:** Learn about common options in [“Customizing Starlight”](/guides/customization/). +- **Navigate:** Set up your sidebar with the [“Sidebar Navigation”](/guides/sidebar/) guide. +- **Components:** Discover built-in cards, tabs, and more in the [“Components”](/guides/components/) guide. +- **Deploy:** Publish your work with the [“Deploy your site”](https://docs.astro.build/en/guides/deploy/) guide in the Astro docs. ## Updating Starlight :::tip -Because Starlight is beta software, there will be frequent updates and improvements. Be sure to update Starlight regularly! +Because Starlight is beta software, there will be frequent updates and improvements. +Be sure to update Starlight regularly! ::: Starlight is an Astro integration, and is updated like any `@astrojs/*` integration: @@ -93,7 +127,6 @@ Starlight is an Astro integration, and is updated like any `@astrojs/*` integrat ```sh -# upgrade Starlight with npm npm install @astrojs/starlight@latest ``` @@ -101,7 +134,6 @@ npm install @astrojs/starlight@latest ```sh -# upgrade Starlight with pnpm pnpm upgrade @astrojs/starlight --latest ``` @@ -109,21 +141,20 @@ pnpm upgrade @astrojs/starlight --latest ```sh -# upgrade Starlight with yarn yarn upgrade @astrojs/starlight --latest ``` -You can see a full list of the changes made in each release in [the Starlight changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md). +See the [Starlight changelog](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md) for a full list of the changes made in each release. ## Troubleshooting Starlight -Both Starlight [project configuration](/reference/configuration/) and [individual page frontmatter configuration](/reference/frontmatter/) information are available in the Reference section of this site. Use these pages to ensure that your Starlight site is configured and functioning properly. - -See the growing list of guides in the sidebar for help adding content and customizing your Starlight site. +Use the [project configuration](/reference/configuration/) and [individual page frontmatter configuration](/reference/frontmatter/) reference pages to ensure that your Starlight site is configured and functioning properly. +See the guides in the sidebar for help adding content and customizing your Starlight site. -If your answer cannot be found in these docs, please visit the [full Astro Docs](https://docs.astro.build) for complete Astro documentation. Your question may be answered by understanding how Astro works in general, underneath this Starlight theme. +If your answer cannot be found in these docs, please visit the [full Astro Docs](https://docs.astro.build) for complete Astro documentation. +Your question may be answered by understanding how Astro works in general, underneath this Starlight theme. You can also check for any known [Starlight issues on GitHub](https://github.com/withastro/starlight/issues), and get help in the [Astro Discord](https://astro.build/chat/) from our active, friendly community! Post questions in our `#support` forum with the "starlight" tag, or visit our dedicated `#starlight` channel to discuss current development and more! From addba897d9f469bcc71cdb6b2f1cfef5ddf891c4 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Thu, 2 Nov 2023 17:02:36 +0100 Subject: [PATCH 2/4] Add manual setup link Co-authored-by: Sarah Rainsberger --- docs/src/content/docs/getting-started.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index e0112d54a7..ad70bd7958 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -7,6 +7,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; Starlight is a full-featured documentation theme built on top of the [Astro](https://astro.build) framework. This guide will help you get started with a new project. +See the [manual setup instructions](/manual-setup/) to add the Starlight integration to an existing project. ## Quick Start From 2423b90d0fbbf70e05ec5b738c1c242fa8dbce82 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Thu, 2 Nov 2023 21:45:51 +0100 Subject: [PATCH 3/4] Use file tree and `example.com` in file-based routing section --- docs/src/content/docs/getting-started.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index ad70bd7958..d1462840b9 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -93,7 +93,20 @@ You can add support for Markdoc by installing the experimental [Astro Markdoc in Add new pages to your site by creating `.md` or `.mdx` files in `src/content/docs/`. Use sub-folders to organize your files and to create multiple path segments. -For example, a file at `src/content/docs/hello-world.md` will be published at `your-site.com/hello-world` and a file at `src/content/docs/guides/faq.md` will be published at `your-site.com/guides/faq`. +For example, the following file structure will generate pages at `example.com/hello-world` and `example.com/guides/faq`: + +import FileTree from '../../components/file-tree.astro'; + + + +- src/ + - content/ + - docs/ + - guides/ + - faq.md + - hello-world.md + + #### Type-safe frontmatter From 2b864ab98714c9a792e8c669e9a01ca3b6b2d1a4 Mon Sep 17 00:00:00 2001 From: Chris Swithinbank Date: Thu, 2 Nov 2023 22:47:47 +0100 Subject: [PATCH 4/4] Avoid themetigration in first paragraph --- docs/src/content/docs/getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index d1462840b9..a08e152bef 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -7,7 +7,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; Starlight is a full-featured documentation theme built on top of the [Astro](https://astro.build) framework. This guide will help you get started with a new project. -See the [manual setup instructions](/manual-setup/) to add the Starlight integration to an existing project. +See the [manual setup instructions](/manual-setup/) to add Starlight to an existing Astro project. ## Quick Start