Make getting-started less of a lie

1 files changed, 29 insertions, 17 deletions

diff --git a/docs/src/content/docs/getting-started.md b/docs/src/content/docs/getting-started.md
index 64d87255..10e0b731 100644
--- a/docs/src/content/docs/getting-started.md
+++ b/docs/src/content/docs/getting-started.md
@@ -2,40 +2,52 @@
 title: Getting Started
 ---
 
-Welcome to Starlight, an intuitive and user-friendly website builder that allows you to easily create and manage your documentation website. In this introductory guide, we will explore the main features and benefits of Starlight.
+Welcome to Starlight, an intuitive and user-friendly framework ideal for documentation websites. In this introductory guide, we will explore the main features and benefits of Starlight.
 
-## Getting Started with Starlight
+## Getting started with Starlight
 
-To get started with Starlight, you will first need to install it. Starlight is built on top of the [Astro](https://astro.build) all-in-one framework, which means you will also need to install Astro before installing Starlight. Once both are installed, you can create a new Starlight project using the following command:
+Starlight is built on top of the [Astro](https://astro.build) all-in-one framework. You can create a new Astro + Starlight project using the following command:
 
 ```sh
 # create a new project with npm
 npm create astro --template starlight
 ```
 
-This will create a new project directory with all the necessary files and configurations for your documentation website.
+This will create a new project directory with all the necessary files and configurations for your site.
 
-## Creating Content with Starlight
+## What’s in the box?
 
-Starlight supports authoring content in Markdown and MDX, which means you can write your documentation using a simple and easy-to-learn syntax. You can also use a range of features and components supported by Docusaurus, GitBook, VitePress, MkDocs, Nextra, and Sphinx, including:
+Starlight includes all the features you need to get a documentation site up and running quickly:
 
+- Easy-to-read typographic styles
 - Syntax highlighting for code blocks
-- Tables and lists
-- Image and video embedding
-- Inline HTML and CSS styling
-- Navigation and sidebar menus
-- Search functionality
+- Simple-to-configure navigation menus
+- Built-in site search
+- [Internationalization features](/guides/i18n)
+- Mix components (from any framework!) and content in MDX
+- Support for custom styles
 
 With these features, you can create rich and engaging documentation that is easy to read and understand.
 
-### Customizing Your Starlight Website
+## Creating content with Starlight
 
-One of the main benefits of Starlight is its flexibility and customization options. You can easily customize your website's layout, theme, and styling using the Astro framework's built-in tools and features. For example, you can customize your website's color scheme, fonts, and typography, as well as add custom components and plugins.
+Starlight supports authoring content in Markdown and MDX.
 
-### Deploying Your Starlight Website
+Adding new pages is done by adding a new `.md` or `.mdx` file to `src/content/docs/`. For example, `src/content/docs/hello-world.md` will be available on your site at `/hello-world`.
 
-Once you have created and customized your Starlight website, you can deploy it to a web server or hosting platform of your choice. Astro provides built-in support for several popular hosting platforms, including Netlify and Vercel, which means you can deploy your website with just a few simple commands.
+All Starlight pages share a common set of frontmatter properties you can set to control how the page appears:
 
-## Conclusion
+```md
+---
+title: Hello, World!
+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. Astro provides built-in support for several popular hosting platforms, including Netlify, Vercel, and GitHub Pages, which means you can deploy your website with just a few simple commands.
 
-Starlight is a powerful and flexible website builder that makes it easy to create and manage your documentation website. With support for Markdown and MDX, as well as a range of features and components, you can create rich and engaging content that is easy to read and understand. So why not give Starlight a try today and see how it can help you take your documentation to the next level!
+[Learn about deploying an Astro site in the Astro docs.](https://docs.astro.build/en/guides/deploy/)