跳转到内容
GabrielxDocs
Blog

使用 Starlight 构建个人知识库

- 最后更新：
GabrielxD
GabrielxD
docs.gab.moe

介绍

Starlight 是一个基于 Astro 框架构建的全功能文档主题。

安装

官方文档教程：Starlight - 开始使用 - 快速入门。

具体步骤

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

    终端窗口
    1
    npm create astro@latest -- --template starlight

  2. 根据提示补充信息：

    输出
    1
     astro   Launch sequence initiated.
    2
    

    3
       dir   Where should we create your new project?
    4
             ./galactic-galaxy
    5
          ◼  tmpl Using starlight as project template
    6
    

    7
        ts   Do you plan to write TypeScript?
    8
             Yes
    9
    

    10
       use   How strict should TypeScript be?
    11
             Strict
    12
    

    13
      deps   Install dependencies?
    14
             Yes
    15
    

    16
       git   Initialize a new git repository?
    17
             Yes
    18
    

    19
         ✔   Project initialized!
    20
             ■ Template copied
    21
             ■ TypeScript customized
    22
             ■ Dependencies installed
    23
             ■ Git initialized
    24
    

    11 collapsed lines
    25
      next   Liftoff confirmed. Explore your project!
    26
    

    27
             Enter your project directory using cd ./galactic-galaxy
    28
             Run pnpm dev to start the dev server. CTRL+C to stop.
    29
             Add frameworks like react or tailwind using astro add.
    30
    

    31
             Stuck? Join us at https://astro.build/chat
    32
    

    33
    ╭─────╮  Houston:
    34
    │ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
    35
    ╰──🍫─╯

  3. 启动开发服务器：

    终端窗口
    1
    npm run dev

个性化配置

配置为中文单语言网站

官方文档教程：Starlight - 国际化 (i18n) - 配置 i18n - 使用root 语言 - 单语言网站

astro.config.mjs
1
// @ts-check
2
import { defineConfig } from 'astro/config';
3
import starlight from '@astrojs/starlight';
4


5
// https://astro.build/config
6
export default defineConfig({
7
  integrations: [
8
    starlight({
9
      ...,
10
      locales: {
11
        root: {
12
          label: '简体中文',
13
          lang: 'zh-CN',
14
        },
15
      },
16
      ...,
17
    }),
18
  ],
19
});

翻译博客 UI

官方文档关于翻译 UI 的逐步教程：Starlight - 国际化 (i18n) - 翻译 Starlight 的 UI

  1. 在 src/content/config.ts 中配置 i18n 数据集合：

    src/content/config.ts
    1
    import { defineCollection } from 'astro:content';
    2
    import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
    3
    

    4
    export const collections = {
    5
        docs: defineCollection({ schema: docsSchema() }),
    6
        i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
    7
    };

  2. 为简体中文在 src/content/i18n/ 中创建一个 JSON 翻译文件：

    • 文件夹src/
      • 文件夹content/
        • 文件夹i18n/
          • zh-CN.json

  3. 添加翻译：

    src/content/i18n/zh-CN.json
    1
    {
    2
        "expressiveCode.copyButtonCopied": "已复制！",
    3
        "expressiveCode.copyButtonTooltip": "复制到剪贴板",
    4
        "expressiveCode.terminalWindowFallbackTitle": "终端窗口"
    5
    }

修复代码块选中时的背景颜色与 ins 块背景颜色难以区分的问题

astro.config.mjs
4 collapsed lines
1
// @ts-check
2
import { defineConfig } from 'astro/config';
3
import starlight from '@astrojs/starlight';
4


5
// https://astro.build/config
6
export default defineConfig({
7
  integrations: [
8
    starlight({
9
      ...,
10
      expressiveCode: {
11
        useThemedSelectionColors: true,
12
        styleOverrides: {
13
          codeSelectionBackground: '#0366d625', // 代码块选中时的背景颜色：半透明天蓝色
14
        }
15
      },
16
      ...,
17
    }),
18
  ],
19
});

安装插件

Starlight Blog

Starlight Blog 文档逐步安装教程：Starlight Blog - Installation。

翻译 Starlight Blog UI

Starlight Blog 文档中扩展的翻译 schema：Starlight Blog - Guides - Internationalization (i18n) - Translate the blog UI

src/content/i18n/zh-CN.json
1
{
2
    "expressiveCode.copyButtonCopied": "已复制！",
3
    "expressiveCode.copyButtonTooltip": "复制到剪贴板",
4
    "expressiveCode.terminalWindowFallbackTitle": "终端窗口",
5
    "starlightBlog.authors.count_one": "{{author}} 的 {{count}} 篇文章",
6
    "starlightBlog.authors.count_other": "{{author}} 的 {{count}} 篇文章",
7
    "starlightBlog.pagination.prev": "较新的文章",
8
    "starlightBlog.pagination.next": "更早的文章",
9
    "starlightBlog.post.lastUpdate": " - 最后更新：{{date}}",
10
    "starlightBlog.post.draft": "草稿",
11
    "starlightBlog.post.featured": "精选",
12
    "starlightBlog.post.tags": "标签：",
13
    "starlightBlog.rss.imageFallback": "原始图片可在博文中查看。",
14
    "starlightBlog.sidebar.all": "所有文章",
15
    "starlightBlog.sidebar.featured": "精选文章",
16
    "starlightBlog.sidebar.recent": "最近文章",
17
    "starlightBlog.sidebar.tags": "标签",
18
    "starlightBlog.sidebar.authors": "作者",
19
    "starlightBlog.sidebar.rss": "RSS",
20
    "starlightBlog.tags.count_one": "有标签“{{tag}}” 的 {{count}} 篇文章",
21
    "starlightBlog.tags.count_other": "有标签“{{tag}}” 的 {{count}} 篇文章"
22
}

ExpressiveCode 的可选插件两则

官方给出的使用方法非常详尽：可折叠代码块 & 行号

书写体验

使用 Prettier 格式化

在 Astro 中使用 Prettier 格式化：Astro Tips - Tips - Setting up Prettier

  1. 安装 prettier 和 prettier-plugin-astro

    终端窗口
    1
    npm i -D prettier prettier-plugin-astro

  2. 在项目根目录创建 .prettierrc 配置文件：

    .prettierrc
    1
    {
    2
      "printWidth": 100,
    3
      "semi": true,
    4
      "singleQuote": true,
    5
      "tabWidth": 2,
    6
      "trailingComma": "es5",
    7
      "useTabs": false,
    8
      "plugins": ["prettier-plugin-astro"],
    9
      "overrides": [
    10
        {
    11
          "files": ["*.md", "*.mdx"],
    12
          "options": {
    13
            "printWidth": 80
    14
          }
    15
        }
    16
      ]
    17
    }
标签：