文档指南

本指南旨在为产品写作者和开发者提供清晰、可操作的步骤，帮助您在基于 Starlight 的文档站点中有效地扩展与维护内容。

项目运行

1. 克隆项目到本地： git 地址

2. 安装依赖：

   npm

   npm i

   pnpm

   pnpm i

   yarn

   yarn

3. 启动项目：

   npm

   npm run dev

   pnpm

   pnpm dev

   yarn

   yarn dev

4. 浏览器访问： http://localhost:4321/zh-cn/

---

创作内容

• astro.sidebar.ts 侧边栏菜单配置
• 文件夹src

  • 文件夹content

    • 文件夹docs 文档内容

      • en 英文文档所在文件夹
      • 文件夹cn 中文文档所在文件夹

        • 文件夹common 行业通用

          • index.mdx 首页/概览
          • 文件夹group1 分组 1

            • doc1.mdx
            • doc2.mdx
            • …
          • 文件夹group2 分组 2

            • doc1.mdx
            • doc2.mdx
            • …
        • 文件夹construction 建筑行业

          • index.mdx
          • …
        • 文件夹manufacturing 制造行业

          • index.mdx
          • …
        • 文件夹infrastructure 数智基建

          • index.mdx
          • …
    • 文件夹nav 菜单翻译词组

      • cn.ts 菜单中文翻译
      • en.ts 菜单英文翻译

添加 页面

直接在对应文件夹中创建文件

添加 分组

1. 在对应文件夹下创建文件夹

2. 在 astro.sidebar.ts 中添加配置：

   astro.sidebar.ts

   export const sidebar = [
    group('construction', {
      items: [
        'construction',
        group('construction.project', {
          autogenerate: { directory: 'construction/project' },
          // or items
        }),
      ]
    }),
    group('manufacturing', {
      items: [
        'manufacturing',
        group('manufacturing.project', {
          autogenerate: { directory: 'manufacturing/project' }
        }),
      ]
    }),
   ] satisfies StarlightUserConfig['sidebar'];

   提示

   可前往 starlight菜单 详细了解菜单配置

3. 在 src/content/nav/cn.ts & en.ts 中添加 中文 & 英文 翻译词组

常用Frontmatter

xxx.mdx

---
title: 文档标题
# 建议填写，将被搜索引擎和社交媒体预览捕获
description: 简介。
# 从生产版本中排除此页面
draft: true
---

国际化

VSCode 插件：starlight-i18n 帮助翻译 Starlight 页面的 Visual Studio Code 扩展。
基于git，比对不同语言的文件夹目录内容，给出还未翻译的文件列表。
注意：新文件须提交到git后，才能被识别。

---

转换成PDF

• 转换单个页面

  建议使用浏览器自带功能：Ctrl + P

• 转换整个解决方案

  行业通用

  npx starlight-to-pdf -u http://localhost:4321/cn/common/

  建筑行业

  npx starlight-to-pdf -u http://localhost:4321/cn/construction/

  制造行业

  npx starlight-to-pdf -u http://localhost:4321/cn/manufacturing/

  数智基建

  npx starlight-to-pdf -u http://localhost:4321/cn/infrastructure/

---

VSCode插件推荐

Astro Astro语言支持

MDX MDX语言支持

MDX Preview MDX文件实时预览