跳转到内容

开始使用

Starlight 是一个基于 Astro 框架构建的全功能文档主题。 这个指南将帮助你开始一个新项目。 查看手动配置以将 Starlight 添加到现有的 Astro 项目中。

快速入门

创建一个新项目

在你的终端中运行以下命令来创建一个新的 Astro + Starlight 项目:

Terminal window
npm create astro@latest -- --template starlight

这将创建一个新的项目目录,其中包含你网站所需的所有文件和配置。

启动开发服务器

在本地工作时,Astro 的开发服务器使你能预览你的工作,并在你进行更改时自动刷新你的浏览器。

在你的项目目录中,运行以下命令来启动开发服务器:

Terminal window
npm run dev

这将在你的终端上记录一个包含本地预览网址的消息。 打开这个网址开始浏览你的网站。

添加内容

Starlight 已经准备好让你添加新内容或导入你现有的文件!

文件格式

Starlight 支持使用 Markdown 和 MDX 编写内容,无需进行任何配置。 你可以通过安装实验性的 Astro Markdoc 集成来添加对 Markdoc 的支持。

添加页面

通过在 src/content/docs/ 中创建 .md.mdx 文件来为你的站点添加新页面。 使用子文件夹来组织你的文件并创建多个路径段。

例如,以下文件结构将在 example.com/hello-worldexample.com/guides/faq 生成页面:

  • Directorysrc/
    • Directorycontent/
      • Directorydocs/
        • Directoryguides/
          • faq.md
        • hello-world.md

类型安全的 frontmatter

所有 Starlight 页面都共享一个可自定义的 frontmatter 属性集,用于控制页面的外观:

---
title: Hello, World!
description: This is a page in my Starlight-powered site
---

如果你忘记了任何重要的东西,Starlight 会提醒你。

下一步

更新 Starlight

Starlight 是一个 Astro 集成,可以像任何 @astrojs/* 集成一样更新:

Terminal window
npm install @astrojs/starlight@latest

查阅 Starlight 更新日志中每个版本的变更列表。

Starlight 故障排除

本站点的参考部分提供了 Starlight 项目配置单个页面 frontmatter 配置信息。使用这些页面来确保你的 Starlight 网站已正确配置和运行。 请参阅侧边栏中的指南列表,以获取有关添加内容和自定义 Starlight 网站的帮助。

如果你在这些文档中找不到答案,请访问完整的 Astro 文档 以获取完整的 Astro 文档。 你的问题可能是通过了解 Starlight 主题下 Astro 的工作原理来解决的。

你也可以检查任何已知的 GitHub 上的 Starlight issues,并在 Astro Discord 上从我们活跃的、友好的社区中获得帮助!在我们的 #support 论坛中发布带有 “starlight” 标签的问题,或者访问我们专门的 #starlight 频道来讨论当前的开发和更多内容!