Astro 主题

Find the theme for you Launch your next site at light speed with our catalog of free and premium Astro themes 找到适合你的主题 使用我们的免费和高级Astro主题目录,以光速启动您的下一个网站

  • https://www.astrojs.cn/zh-cn/basics/layouts/

  • https://astro.nodejs.cn/en/tutorial/0-introduction/

  • https://astro.build/themes

  • Blogs Whether you want sleek minimalism or bold colors, find the blog template for you. Browse blog themes 

  • E-commerce Every second counts. Find an e-commerce template that loads fast and looks great. Browse e-commerce themes 

  • Landing pages Showcase your product or service with a stylish landing page template. Browse landing page themes 

  • Portfolio Share your art, coding projects, music, and more with an Astro portfolio theme. Browse portfolio themes 

  • Documentation Ship your next technical documentation website with an Astro docs theme. Browse docs themes  …and more! Discover all Astro themes and filter by your favorite technology, from Tailwind to Vue.

  • 博客 无论你想要时尚的极简主义还是大胆的颜色,都可以找到适合你的博客模板。 浏览博客主题

  • 电子商务 每一秒都很重要。找到一个加载速度快、看起来很棒的电子商务模板。 浏览电子商务主题

  • 登录页 使用时尚的登录页面模板展示您的产品或服务。 浏览登录页面主题

  • 文件夹 通过Astro作品集主题分享您的艺术、编码项目、音乐等。 浏览作品集主题

  • 文档 在您的下一个技术文档网站上发布Astro-docs主题。 浏览文档主题

…还有更多! 探索所有Astro主题,并使用您最喜欢的技术进行过滤,从Tailwind到Vue。

Starlight

  • 官方文档:https://starlight.astro.build/zh-cn/getting-started/
  • 主题地址:https://github.com/withastro/starlight/tree/main/examples/basics

Starlight Starter Kit:基础入门

Built with Starlight (使用 Starlight 构建)

npm create astro@latest -- --template starlight

运行终端显示:

PS G:\web\node.js\WebstormProjects> npm create astro@latest -- --template starlight

 astro   Launch sequence initiated.

   dir   Where should we create your new project?
         ./docs
      ◼  tmpl Using starlight as project template

  deps   Install dependencies?
         Yes

   git   Initialize a new git repository?
         Yes

      ▲  error Error: Timeout
      ▲  error Dependencies failed to install, please run npm install to install them manually after setup.
      ✔  Project initialized!                                                                                                                                    
         ■ Template copied
         ■ Dependencies installed
         ■ Git initialized

  next   Liftoff confirmed. Explore your project!

         Enter your project directory using cd ./docs                                                                                                            
         Run npm run dev to start the dev server. CTRL+C to stop.
         Add frameworks like react or tailwind using astro add.

         Stuck? Join us at https://astro.build/chat           
使用cd输入项目目录。/docs
运行npm Run-dev启动dev服务器。按CTRL+C停止。
使用astro Add添加诸如react或tailwind之类的框架。
卡住了?加入我们https://astro.build/chat           

启动开发服务器

cd docs
npm run dev
npm install && npm run dev

🚀 项目结构

在你的 Astro + Starlight 项目中,你会看到以下文件夹和文件:

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Starlight 会在 src/content/docs/ 目录中查找 .md.mdx 文件。每个文件会根据其文件名被暴露为一个路由。

图片可以添加到 src/assets/ 目录,并在 Markdown 中使用相对链接嵌入。

静态资源,如 favicon,可以放在 public/ 目录中。

🧞 命令

所有命令都在项目的根目录下从终端运行:

CommandAction (动作)
npm install安装依赖项
npm run devlocalhost:4321 启动本地开发服务器
npm run build将生产环境站点构建到 ./dist/ 目录
npm run preview在部署前本地预览你的构建
npm run astro ...运行 CLI 命令,如 astro add, astro check
npm run astro -- --help获取使用 Astro CLI 的帮助

👀 想了解更多?

查看 Starlight 的文档,阅读 Astro 文档,或加入 Astro Discord 服务器

添加内容

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

通过在 src/content/docs/ 目录中创建 Markdown 文件来为你的网站添加新页面。

在 “页面” 指南中了解有关基于文件的路由和对 MDX 和 Markdoc 文件的支持的更多信息。

配置 i18n

移动文件夹 index.mdx index-zh-cn.mdx index-en.mdx index-ar.mdx

安装Astro和Starlight

参照这个文档:https://junxuanb.com/zh-cn/blog/241005a-astro/ 首先需要安装npm和node.js。MacOS用户可以通过管理 nvm 管理node.js版本并使用 Homebrew https://brew.sh/ 进行软件安装。

Markdown
brew install nvm # 安装nvm
nvm ls-remote # 查看所有可用的node版本
nvm install --lts # 安装最新的LTS版本
brew install npm # 安装npm
node -v # 查看node版本
npm -v # 查看npm版本

在确认安装了正确的node和npm版本后,我们可以进入目标文件夹的上一级目录,运行以下命令:

Markdown
npm create astro@latest -- --template starlight # 创建一个新的Astro项目并使用Starlight模板
cd my-astro-site # 进入项目文件夹
npm install # 安装依赖(可以跳过,在执行npm create时已经安装了依赖)
npm run dev # 运行开发服务器

之后就可以在浏览器中访问http://localhost:4321查看你的网站了。

配置Cloudflare Pages

Cloudflare Pages是一个完全免费的静态网站托管服务,支持自动部署和自定义域名。并且在测速对比中,在大部分地区的速度都优于GitHub Pages。

在完成项目配置并上传至GitHub后,我们可以前往Cloudflare Pages进行项目部署。

首先,你需要注册一个Cloudflare账号并登录 在左侧导航栏中选择Workers和Pages,然后点击创建 填写GitHub仓库地址后方可自动完成部署(无需手动打包) 之后每次push代码都会自动打包并部署

推荐插件

Astro官方Starlight社区中有许多优秀的插件,这是我正在使用和推荐的几个:

Astro + Cloudflare Pages 快速搭建个人博客 https://blog.csdn.net/2201_75791084/article/details/141217097 部署你的 Astro 站点至 Cloudflare Pages https://tanggd.github.io/zh-cn/guides/deploy/cloudflare/

Git命令总结

提交并推送到 GitLab

Markdown
#  首次推送时如果远程仓库已有文件(如 README),需要先拉取
git pull origin main --allow-unrelated-histories  

git clone            
git rm -r --cached .  # 清除所有缓存

git remote add origin https://github.com/<your-gh-username>/<repository-name>

git remote add origin https://github.com/maiyixyz/docs

git add .gitmodules themes/ config.toml .gitlab-ci.yml

git add .
git commit -m "切换至自定义主题"
git push origin master

git branch -M main
git push -u origin main



git push   # 自动推送到 origin/main
git pull   # 自动从 origin/main 拉取

详细解释 Git 命令含义

1. git add .

  • 作用:将当前目录下的所有修改添加到 Git 暂存区(Staging Area)
  • 分解说明
    • git:Git 版本控制系统的命令
    • add:添加文件到暂存区的指令
    • .:代表当前目录及其所有子目录
  • 实际效果
    • 跟踪所有新增文件(如新创建的 Markdown 文件)
    • 暂存所有修改过的文件(如编辑过的 config.toml
    • 标记所有删除的文件(如被移除的默认内容)
  • 类比:像超市购物时把商品放入购物车(暂存区),准备结账

2. git commit -m "切换至自定义主题"

  • 作用:将暂存区的修改正式提交到本地仓库
  • 分解说明
    • commit:创建版本快照的指令
    • -m:允许直接添加提交信息的参数(message 缩写)
    • "切换至自定义主题":本次提交的描述信息
  • 关键点
    • 创建唯一的提交 ID(如 c3f45d2
    • 永久记录文件变更状态
    • 提交信息应清晰描述本次修改目的
  • 类比:超市购物车里的商品结账打包,贴上标签说明内容

3. git push origin main

  • 作用:将本地提交推送到远程仓库
  • 分解说明
    • push:推送本地修改到远程的指令
    • origin:默认远程仓库别名(通常指向 GitLab/GitHub 地址)
    • main:分支名称(GitHub 等平台的新默认分支名)
  • 执行过程
    1. 连接远程仓库(如 https://gitlab.com/yourname/hugo-site.git
    2. 上传本地 main 分支的所有新提交
    3. 触发 GitLab CI/CD 自动构建(根据 .gitlab-ci.yml 配置)
  • 类比:把打包好的商品快递到仓库(远程服务器)

完整流程示意图

  graph LR
    A[工作目录] -- git add . --> B[暂存区]
    B -- git commit -m --> C[本地仓库]
    C -- git push origin main --> D[远程仓库]
    D --> E[触发 CI/CD 构建]
    E --> F[网站自动部署]

实际执行示例

# 1. 添加所有变更文件
$ git add .
# 输出:无提示(可用 git status 查看)

# 2. 提交到本地仓库
$ git commit -m "切换至自定义主题"
# 输出示例:
[main 3a8b7e2] 切换至自定义主题
 5 files changed, 23 insertions(+), 8 deletions(-)
 create mode 100644 content/posts/new.md

# 3. 推送到远程
$ git push origin main
# 输出示例:
Enumerating objects: 7, done.
Delta compression using up to 8 threads
To https://gitlab.com/yourname/hugo-site.git
   2e4f5a1..3a8b7e2  main -> main

注意事项

  1. 分支名称

    • 旧项目可能使用 master 而非 main,需保持一致
    • 查看分支:git branch(当前分支前有 * 标记)
  2. 首次推送

    git push -u origin main  # -u 设置默认上游分支
  3. 权限问题

    • 出现 Permission denied 错误时,需配置 SSH 密钥
    • GitLab 设置路径:Profile > SSH Keys
  4. 冲突处理

    • 若远程有更新,需先拉取:git pull origin main
    • 解决冲突后再推送

最佳实践:每次推送前执行 git status 确认变更内容,避免提交错误文件。

这个错误是因为 Git 没有配置用户身份信息导致的。当您执行 git commit 时,Git 需要知道提交者的姓名和邮箱(用于记录版本作者信息)。以下是解决方案:

快速解决方法(在命令行执行):

  1. 设置全局用户信息(推荐,一劳永逸):

    git config --global user.email "您的邮箱@example.com"
    git config --global user.name "您的用户名"

    示例:

    git config --global user.email "john@example.com"
    git config --global user.name "John Doe"
  2. 仅设置当前仓库(如果不想全局配置):

    git config user.email "您的邮箱@example.com"
    git config user.name "您的用户名"

为什么会出现这个错误?

  • Git 提交时必须绑定用户身份
  • 系统自动检测到的邮箱 admin@MYMY-BOSS.(none) 是无效格式
  • Goland 默认使用系统 Git 配置,未配置时就会报错

在 Goland 中配置(图形化操作):

  1. 打开 Settings(设置)
    • Windows/Linux:File > Settings
    • macOS:PyCharm > Preferences
  2. 导航到:Version Control > Git
  3. User 区域填写:
    • Name: 您的用户名(如 John Doe
    • Email: 您的邮箱(如 john@example.com
  4. 点击 Apply 保存

⚠️ 注意:Goland 的图形设置会修改全局 Git 配置(等同于 --global 参数)

验证配置是否成功:

git config --global --list  # 查看全局配置
git config --list           # 查看当前仓库配置

正常应显示:

user.name=您的用户名
user.email=您的邮箱

重要提示:

  • 邮箱和用户名是 Git 提交记录的身份证(会公开显示在历史记录中)
  • 推荐使用 GitHub 等平台注册时相同的邮箱,这样提交会计入您的账户贡献
  • 配置后重新执行 git commit -m "commit" 即可成功提交

💡 如果公司有特殊要求(如使用公司邮箱),请按团队规范配置邮箱地址。

Markdown 示例

文本样式

样式语法示例输出
粗体**粗体文本****粗体文本**粗体文本
斜体*斜体文本**斜体文本*斜体文本
删除线~~删除线文本~~~~删除线文本~~删除线文本
下标<sub></sub>这是一个<sub>下标</sub>文本这是一个下标文本
上标<sup></sup>这是一个<sup>上标</sup>文本这是一个上标文本

引用块

带出处的引用块

不要通过共享内存来通信,而要通过通信来共享内存。
Rob Pike1

Markdown
> 不要通过共享内存来通信,而要通过通信来共享内存。<br>
> — <cite>Rob Pike[^1]</cite>

[^1]: 以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的[演讲](https://www.youtube.com/watch?v=PAAkCSZUG1c)。

提示框

New in v0.9.0

提示框是基于引用块语法的 Markdown 扩展,可用于强调关键信息。 支持 GitHub 风格的提示框。 请确保您使用的是最新版本的 MaiyiDocs 和 Hugo v0.146.0 或更高版本。

Note

用户应该知道的有用信息,即使是在浏览内容时。

Tip

帮助用户更好地或更轻松地完成任务的建议。

Important

用户需要了解的关键信息,以实现他们的目标。

Warning

需要用户立即注意的紧急信息,以避免问题。

Caution

关于某些操作的风险或负面结果的建议。

Markdown
> [!NOTE]
> 用户应该知道的有用信息,即使是在浏览内容时。

> [!TIP]
> 帮助用户更好地或更轻松地完成任务的建议。

> [!IMPORTANT]
> 用户需要了解的关键信息,以实现他们的目标。

> [!WARNING]
> 需要用户立即注意的紧急信息,以避免问题。

> [!CAUTION]
> 关于某些操作的风险或负面结果的建议。

列表

有序列表

  1. 第一项
  2. 第二项
  3. 第三项
Markdown
1. 第一项
2. 第二项
3. 第三项

无序列表

  • 列表项
  • 另一个项
  • 再一个项
Markdown
* 列表项
* 另一个项
* 再一个项

嵌套列表

  • 水果
    • 苹果
    • 橙子
    • 香蕉
  • 乳制品
    • 牛奶
    • 奶酪
Markdown
* 水果
  * 苹果
  * 橙子
  * 香蕉
* 乳制品
  * 牛奶
  * 奶酪

图片

风景

Markdown
![风景](https://picsum.photos/800/600)

带标题:

风景
Unsplash 风景

Markdown
![风景](https://picsum.photos/800/600 "Unsplash 风景")

  1. 以上引用摘自 Rob Pike 在 2015 年 11 月 18 日 Gopherfest 上的演讲。 ↩︎